[[system_configuration]]
== Configuration
Configuration of Helix Web Services is split into a main file, and individual files that indicate each p4d individually, see <<p4d_settings>>.
You will need both the main file and at least one p4d configuration.
[[settings]]
=== Main Helix Web Services Settings
Most of these settings are available in the configuration file typically installed within the package at `/opt/perforce/helix-web-services/etc/helix-web-services.conf`, or in the subdirectory `etc` of wherever you unpacked the binary archive distribution.
[cols="4*", options="header"]
|===
| Variable
| Type
| Description
| Default
| `ACCESS_CONTROL_ALLOW_ORIGIN`
| String
| Value for the `Access-Control-Allow-Origin` CORS header.
| *
| `ACCESS_CONTROL_ALLOW_HEADERS`
| String
| Value for the `Access-Control-Allow-Headers` CORS header.
| *
| `ACCESS_CONTROL_REQUEST_METHOD`
| String
| Value for the `Access-Control-Request-Method` CORS header.
| *
| `AUTO_TRUST`
| Boolean
| Enable auto-trusting all new servers that this service is connecting to. If previously trusted will throw an error if fingerprint changed
| false
| `COMMAND_WHITELIST`
| Array
| Allows access to run commands via <<GET /api/p4d/v16.1/{server}/commands/{command}>> or <<POST /api/p4d/v16.1/{server}/commands/{command}>>.
Each element in the array is either the name of a command to allow, or an array of the command name and any required arguments.
| `["info", ["files", "-m"]]`
| `DEFAULT_API_LEVEL`
| String
| The api level (e.g., "80") to use for P4 connections.
If set, we'll use this instead of associating it with the platform version we're targeting.
|
| `ENABLE_GIT_FUSION`
| Boolean
| Switch to enable GitFusion endpoints.
| false
| `ENABLE_HTTPS`
| Boolean
| Configure the web server to use HTTPS.
You must configure the keystore file: see `KEYSTORE_FILE` setting.
Related optional settings are: `KEYSTORE_PASSWORD`, `TRUSTSTORE_FILE`, and `TRUSTSTORE_PASSWORD`.
| false
| `GITFUSIONDEPOT`
| String
| The depot name for Git Fusion data.
This makes no sense to use if `ENABLE_GIT_FUSION` is false.
| .git-fusion
| `HWS_PORT`
| Number
| The port to respond to for new connections.
| 9000
| `HWS_AUTH_P4D`
| String
| The P4D id to use as the authentication server if the server is not
specified in request parameters with a URL like <<POST /api/p4d/v16.1/{server}/commands/{command}>>.
This id must match one of the id values in the files that specify P4D
configuration in `P4DCONFIGDIR`
<<POST /api/hws/v16.1/login>> requires this to be set to a valid value.
|
| `KEYSTORE_FILE`
| String
| The keystore file for secure connections.
|
| `KEYSTORE_PASSWORD`
| String
| The password for the keystore.
|
| `MAX_SERVER_CONNECTIONS`
| Number
| The maximum number of connections we'll allow this instance to acquire per P4PORT
| 50
| `P4DCONFIGDIR`
| String
| The local directory where p4d configuration settings files are stored.
These are yaml files, named with the the value of `P4DID`.
|
| `TRUST_FINGERPRINTS`
| String
| Local file path that indicates a list of allowed SSL fingerprints.
|
| `TRUSTSTORE_FILE`
| String
| The path to the truststore file, if empty, will reuse the keystore.
|
| `TRUSTSTORE_PASSWORD`
| String
| The password for the truststore file.
|
|===
[[p4d_settings]]
==== P4D Configuration
Each instance of p4d you use should be registered in by creating a file in the `P4DCONFIGDIR`, set in the main configuration file.
Each p4d configuration file is a YAML document with the following properties:
[cols="3*", options="header"]
|===
| Property
| Required
| Description
| `id`
| Yes
| The ID of the settings, which should be the name of the file and the value you use for `P4DID` to find these settings.
Please do not use complex characters for this ID, simple ASCII alphanumeric strings are recommended.
| `name`
| No
| A string suitable for display to the user
| `description`
| No
| A free text field to indicate the connection's purpose.
| `P4PORT`
| Yes
| The host and ID, optionally preceded by `ssl:` if it is an TLS enabled server.
| `P4CHARSET`
| No
| The character set of the server connections to use, e.g., `utf8`
| `APILEVEL`
| No
| Specify the API level to connect to this server as, e.g., `80`, for 2016.1 p4d.
|===
For example, here is a configuration for the `default` ID that should be in a file called `default`.
In a Unix installation this would be saved at the path `/opt/perforce/helix-web-services/etc/p4d/default`.
[source,yaml]
.default
....
id: default
name: Default
description: Our typical default server
P4PORT: 127.0.0.1:1666
P4CHARSET: utf8
....
[[p4d_settings_ssl]]
===== Configuring the system to use an SSL-enabled P4D
There are a couple of different ways for your HWS instance to establish trust with a P4D, which starts with two options in the <<settings>>:
1. Create a file with trusted fingerprints, and point the option `TRUST_FINGERPRINTS` to this file location.
2. Set the option `AUTO_TRUST` to true.
Your p4d administrator should have written down the trust fingerprint during configuration, see https://www.perforce.com/perforce/doc.current/manuals/p4sag/chapter.security.html#DB5-58511[the Securing the Server section of the Helix Versioning Engine Administrator Guide].
If you do not have access to this information, you can obtain this information via any p4 client, typically by attempting to communicate this server on a machine that has not already trusted it.
By executing any command, you will see a message like the following:
....
$ p4 -p ssl:perforce:1667 info
The authenticity of '123.45.67.89:1667' can't be established,
this may be your first attempt to connect to this P4PORT.
The fingerprint for the key sent to your client is
B7:92:0F:86:1C:5D:44:10:AA:FF:D9:62:5C:AF:49:00:4B:59:C3:7C
To allow connection use the 'p4 trust' command.
....
You should verify with your administrator that indeed the fingerprint `B7:92:0F:86:1C:5D:44:10:AA:FF:D9:62:5C:AF:49:00:4B:59:C3:7C` is correct, and then put that into a file on the HWS machine.
And then configure `TRUST_FINGERPRINTS` to be that file.
When `AUTO_TRUST` is used, the HWS server will automatically setup trust for the P4D server _on the first connection only_ after HWS has started.
Thus, if the p4d trust changes during runtime, all requests after that change will fail.
NOTE: Using a command line client, like `p4` on the HWS machine should have no effect on how HWS connects to p4d.
The `p4` command line client is a user application, and will create files in your user's home directory to cache values, such as login tokens and trust fingerprints.
It is *not recommended* to use the system account that HWS executes as to run the `p4` command line.
While HWS should ignore these values, you may find that upgrade or installation procedures deletes or removes your previous `p4` setup.
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #22 | 19738 | swellard | Tweak to HWS_AUTH_P4D | ||
| #21 | 19731 | tjuricek |
Add admonition paragraph that people generally shouldn't do things as the system account HWS runs as. There is *no reason* to do this in general. |
||
| #20 | 19730 | tjuricek | Add documentation on setting up a fingerprints file for HWS. | ||
| #19 | 19719 | swellard | Add HWS_AUTH_P4D to docs | ||
| #18 | 19601 | swellard | Refactor REST path - doc tweaks | ||
| #17 | 19473 | tjuricek | Adding notes to setup the p4d configuration file during quick start, and try to clarify the authentication process a little bit more. | ||
| #16 | 19186 | tjuricek | Revise the p4d configuration file settings documentation. | ||
| #15 | 19185 | tjuricek |
Removing Helix Sync, SSH key logic that is not tested or used. After discussing with Doug Scheirer, we'll need to revisit exactly what an HWS api needs to do with Helix Cloud. The integration may be trickier then most assume, since a large chunk of the API will not be allowed for Cloud users. |
||
| #14 | 19012 | tjuricek | Revised Java client SDK, added ApiClient reference, restructured documentation. | ||
| #13 | 19005 | tjuricek | Correct link references to commands due to "server ID" being added to URLs | ||
| #12 | 19002 | tjuricek |
Improve API to interact with multiple p4ds. The configuration now requires an explicit setting of what P4Ds HWS can talk to via the 'P4D config dir', where there's a file indicating connection settings per p4d, and importantly, an ID. This is the "server ID" referenced everywhere. Most methods now require a server ID to indicate which p4d to manipulate. In the future, it's likely we will interact with *multiple* p4d instances on some services. This completely removes the ability to run HWS as a kind of an "open proxy" to whatever p4d you want. Given the nature of the change and the lack of priority, we've removed Helix Cloud testing and disabled several methods from their "Helix Cloud" implementation. These will be relatively easy to bring back, we'll just need a new method from Raymond that lists the "allowed server IDs" that map to the HWS configured server IDs for a particular user. Another notable aspect of this change is the use of JSON Web Token to create our authentication key. We associate this key with an in-memory "session" that contains the P4D tickets we use to authenticate users. The JWT token, by default, is assigned a timeout, which allows HWS to block further access to underlying servers without having to interact with multiple auth backends. If any backend fails with that session, the user will get a 403. If you disable the timeout, you'll need to ensure your clients clear out sessions. |
||
| #11 | 18830 | tjuricek | Updated "release compatibility" section to reflect 3-number versioning scheme. | ||
| #10 | 18810 | tjuricek |
First-pass at JavaScript client SDK. JavaScript requires Node with Gulp to "browserfy" the library. It's the easiest way I found to use the swagger-js project; bundle up a wrapping method. There is no JavaScript reference guide. The swagger-js doesn't really document what they do very well, actually. Overall I'm not particularly impressed by swagger-js, it was hard to even figure out what the right method syntax was. We may want to invest time in doing it better. This required setting CORS response headers, which are currently defaulted to a fairly insecure setting. |
||
| #9 | 18803 | tjuricek |
Allow for a simple "p4d configuration" mechanism to setup a way for multiple p4ds to be used without having to provide settings like P4PORT, etc via headers. Right now, you'd set P4DCONFIGDIR to a local directory, and the provide a P4DID either as a default in the configuration or via a header. I didn't include it in the path or query parameters, because then it would have been required by clients on *every method call* which seemed like the wrong approach. Most clients will interop primarily with a single server, so creating a client object per server didn't seem ridiculous. |
||
| #8 | 18788 | tjuricek | Correct references to URL paths in asciidoc and add minor release number to default version string. | ||
| #7 | 18693 | tjuricek |
Move from swagger2markdown project to custom asciidoc generator. This gives us flexibility to do include the context path, for example, or alter the output fairly easily. While StringTemplate is a little tricky to get to know, it works pretty well for our needs, and offers a lot more flexibility for reorganization later. Note: I might change the status method to be version-specific, but in the future, we'll have a method "what versions do you support" which will *not* be version-specific. |
||
| #6 | 18681 | tjuricek | Fix link references to the revised URLs | ||
| #5 | 18576 | tjuricek | Update installation instructions to work with linux packages or binary archives. | ||
| #4 | 18551 | tjuricek |
Switch to using swagger-based HTTP methods. Remove old java_client. The swagger documentation generates asciidoc, which is included in the current user guide. We lose some control over the formatting. |
||
| #3 | 17352 | tjuricek | Removing settings unlikely to be needed on the JVM | ||
| #2 | 17339 | tjuricek |
Removed obsolete documentation no longer relevant to JVM-based installation, and created framework for new installation. I do not have exact details on the new system just yet, but I know we'll want the PDF as part of the installation. |
||
| #1 | 17323 | tjuricek |
Revise the documentation to use the JVM-based asciidoctor. This will generate the DocBook XML. I'm still ironing out exactly what the CD process is here. |
||
| //guest/perforce_software/helix-web-services/main/source/doc/03_configuration.asc | |||||
| #17 | 17235 | tjuricek | Enable the ability to run HWS in HTTPS mode. | ||
| #16 | 17228 | tjuricek |
Revising configuration, removing clearly obsolete variables, and renaming some for consistency. Some variables need to remove underscores, because those underscores are actually not really a good idea for HTTP headers. (Some servers block those values as keys, depending on config.) |
||
| #15 | 17140 | tjuricek |
Integrating porting work from development branch. This work is now ready for testing/CD integration. |
||
| #14 | 17109 | tjuricek | Sorting configuration options alphabetically | ||
| #13 | 17108 | ptomiak |
Changes to enable automatic trusts. Implement a setting switch to automatically any new p4d we are talking to - mainly for GitSwarm. If a user will try to authenticate aganist a p4d we never saw before the fingerprint will be automatically accepted and login will carry on as usual. Added doc's section. |
||
| #12 | 17092 | tjuricek | Configure logrotate during post-install configuration. | ||
| #11 | 17090 | tjuricek |
Revised documentation based on edits received (on paper). Removed Helix Web Services ruby client references, since there is no publication plan for this API. |
||
| #10 | 16332 | tjuricek |
Update documentation for new configuration, deployment. Also, fix default location for hws_console. |
||
| #9 | 16280 | tjuricek |
Adjustments for Helix Cloud settings Several tests are now disabled due for Helix Cloud since they won't work on streams, which HC only uses. |
||
| #8 | 16095 | tjuricek | Shorten /helix_versioning_engine URLs to /p4 | ||
| #7 | 16090 | tjuricek |
Rename ENABLE_AUTOMATIC_TRUST to ENABLE_MAN_IN_MIDDLE_ATTACKS and remove documentation. Only use this option for allowing developers to regenerate fingerprints on their own p4ds. |
||
| #6 | 16076 | tjuricek |
Use a TRUST_FINGERPRINTS file to decide which p4 trust fingerprints to accept. If we receive a request that is *not* in this file, and this setting is used, we reject it. This is our recommendation for production servers. The ENABLE_AUTOMATIC_TRUST is only to be used for testing servers. We need this because of a high-cost of the Qt test framework. Revised upon request of Alan Teague and Doug Scheirer. |
||
| #5 | 15969 | tjuricek |
Add support for repo creation/update and deletion, same for SSH keys. Add util module for supporting methods, modify temp client to dissapear. (Modified submit of review 15549 by @ptomiak) |
||
| #4 | 15717 | tjuricek |
Added notes on post-install configuration and uninstallation. It's unclear to me if we should invest significant time into configuration yet or not. |
||
| #3 | 15700 | tjuricek | Allow custom scripts to be loaded into the process in order to modify HWS or add some functionality. | ||
| #2 | 15698 | tjuricek |
Added a /helix_versioning_engine/v[api]/login method This is used by the Helix Sync client to differentiate the auth source of HWS from that of P4D (to be used for projects). |
||
| #1 | 15622 | tjuricek |
Move source code to 'source/' subdirectory of branch. build/ will remain where it is. |
||
| //guest/perforce_software/helix-web-services/main/doc/03_configuration.asc | |||||
| #11 | 15545 | tjuricek | Place in config and hooks for Helix Cloud authentication. | ||
| #10 | 15483 | tjuricek |
Add a new 'hws_console` application to the deployment. This should give users the ability to use the Ruby client for quick and dirty debugging of issues with HWS. Since it's so easy, I've added it to the deployment guide. |
||
| #9 | 15437 | tjuricek |
Basic "HVE Project" implementation. This will allow directories in a HVE instance to host 'projects' for use by helix sync. There are no methods defined for creating the projects, however. This does not include any specialization or testing in the Qt API yet. I may investigate creating a "higher level" interface for Qt client apps. |
||
| #8 | 15297 | tjuricek |
Implement of 'cluster services' configuration. The configuration will be stored in a local JSON file, which is expected to be maintained by the systems admin. Eventually, it's expected to have this sort of thing implemented via Helix Admin. |
||
| #7 | 15257 | tjuricek |
Added stress test, corrected per-request header config. Apparently using underscores is a "special" mechanism for HTTP headers, and requires adjusting nginx to allow such things. Might as well just recommend using hyphens, which get converted to underscores anyway. The current test just hits a listing of 20000 files against p4play. Returns a 2.5 MB response, which doesn't seem to cause problems (yay). |
||
| #6 | 15240 | tjuricek |
Set api level via request path on all Helix Versioning Engine methods. This will allow migration of applications to different P4D versions. Our internal methods (like project API) should attempt to handle backward compatibility similarly. P4WEBAPI-118 |
||
| #5 | 15229 | tjuricek | Remove incorrect default setting for P4HOST | ||
| #4 | 15208 | tjuricek |
Revise 'command' implementation, tests, and documentaiton. This includes a change from a command blacklist to a whitelist. See P4WEBAPI-21 |
||
| #3 | 15110 | tjuricek | Revise changes methods for new p4 connection handling, add server specs, remove model references in client, and update asciidoc documentation. | ||
| #2 | 15090 | tjuricek |
Update _proposed_ API for project services. This is *very likely* to change, and will not be implemented until reviewed. |
||
| #1 | 15038 | tjuricek | Document 'login' auth method and client programming overview. | ||