Helix TeamHub configuration
The Helix TeamHub configuration settings are in the /var/opt/hth/shared/hth.json configuration file. It includes settings manipulated through TeamHub Admin UI. This configuration file is also part of TeamHub Backups, if enabled.
Every time TeamHub is reconfigured, the configuration file is read and the configuration is applied to all of TeamHub services. Some of the configuration flags dictate what mode of deployment TeamHub is running, where others simply override default TeamHub settings.
Format
The configuration file is formatted as JSON. It is important to keep the correct format of the file, otherwise the TeamHub reconfiguration will not work. JSONLint is a trusted open-source JSON linter option to help verify the syntax of the JSON contents.
Remember that duplicate keys override the previously defined keys.
To see the current configuration applied to the server, run the following command:
sudo hth-ctl show-config
Overriding defaults
TeamHub comes with many sensible defaults for both service and application behavior. If the default configuration needs to be adjusted, use the dictionary provided below as a reference.
Each configuration flag has a section, for example app, nginx, etc. These sections separate settings into logical categories. To use the dictionary, simply merge the section to the existing configuration file at /var/opt/hth/shared/hth.json with a required key and value.
Whenever changing any of the configurations, pay attention to the type of the key and where available refer to the linked documentation. Also, remember that configuration is not applied until the sudo hth-ctl reconfigure command has been run.
Section: apache
This section groups TeamHub Apache-related settings.
Key | Type | Default | Description |
---|---|---|---|
limit_request_body | Integer | null | Specifies the number of bytes that are allowed in a request body, see LimitRequestBody Directive |
limit_xml_request_body | Integer | null | Limit (in bytes) on maximum size of an XML-based request body, see LimitXMLRequestBody Directive |
timeout | Integer | 120
|
Defines the length of time Apache httpd will wait for I/O |
Section: app
This section groups instance and general application related settings.
Key | Type | Default | Description |
---|---|---|---|
backups_email
|
String | email |
Allows overriding receiver of backup related emails. |
default_company
|
String | Default company short name to use with login | |
email
|
String | support@FQDN
|
Email of the sender of all outgoing emails and links to Support team |
hostname
|
String | FQDN
|
TeamHub application hostname |
http_proxy
|
String | Defines HTTP proxy to use with external services like hooks. Provide absolute url including possible credentials: http://user:password@proxy.com:8008 . |
|
is_cluster
|
Boolean | false
|
Defines whether TeamHub runs in Enterprise |
is_https | Boolean | false
|
Defines whether TeamHub generates URLs with https or http. |
is_ssl
|
Boolean | false
|
Defines whether TeamHub services are running with SSL using certificates on the server instance (true) or offloaded to a load balancer (false). |
notifications_email
|
String | email |
Allows overriding sender of notification related emails. |
registrations_email
|
String | email |
Allows overriding sender of registration related emails. |
ssh_port
|
Integer | 22 |
Defines SSH port for Git and Mercurial clone urls when the instance is using non-standard SSH port. |
Section: audit
This section groups TeamHub audit logging related settings.
Key | Type | Default | Description |
---|---|---|---|
logrotate_frequency
|
String | daily
|
Frequency of logrotate rotation |
logrotate_rotate
|
Integer | 90
|
Number of logrotate files to keep |
logrotate_size
|
Integer | Size of logrotate rotation. Does not rotate by size by default |
Section: backend
This section groups TeamHub backend (APIs, TeamHub Admin) application-related settings.
Key | Type | Default | Description |
---|---|---|---|
auth_method
|
String |
builtin
|
Defines TeamHub Authentication type. |
backup_s3
|
Boolean | false
|
Defines whether asset backups need to be taken offline to Amazon S3. Requires backups section configuration. |
backups
|
Boolean | false
|
Defines whether TeamHub asset backups are enabled |
command_timeout | Integer | 60 | Timeout for command execution, in seconds. |
company_disk_usage_calculator_queue_size | Integer | 1 | Number of workers performing company disk usage calculation jobs. |
db_host
|
String | localhost
|
MongoDB hostname for Enterprise |
db_password
|
String | MongoDB password | |
db_pool_size
|
Integer | 10
|
MongoDB connection pool size |
db_port
|
Integer | 4002
|
MongoDB port |
db_username
|
String | MongoDB username | |
diff_file_max_bytes
|
Integer | 51200
|
Maximum number of bytes for a file in a diff |
diff_max_bytes
|
Integer | 1024000
|
Maximum number of bytes for a diff output |
diff_max_files
|
Integer | 150
|
Maximum number of files in a diff |
diff_max_lines
|
Integer | 50000
|
Maximum number of lines in a diff |
diff_process_max_bytes
|
Integer | 2048000
|
Maximum number of bytes to process for a diff |
diff_timeout
|
Integer | 5
|
Timeout in seconds for generating a diff |
es_hosts
|
Array | []
|
Array of Elasticsearch host hashes. Supported keys are: host , port , scheme , user , password . |
es_index_prefix
|
String | null
|
Defines the optional index name prefix for Elasticsearch indices. |
es_number_of_replicas
|
Integer | 1
|
Defines the number of replicas for Elasticsearch indices. |
es_number_of_shards
|
Integer | 5
|
Defines the number of shards to use with Elasticsearch indices. |
es_ssl_verify
|
Boolean | true
|
Defines whether to validate Elasticsearch host certificate. |
events_queue_size | Integer | 2 | Number of workers performing event jobs. |
failed_login_interval
|
Integer | 2
|
Minimum time between failed login attempts |
failed_login_limit
|
Integer | 6
|
Limit of failed login attempts in specified time frame |
failed_login_period
|
Integer | 60
|
Time frame for failed_login_limit |
hooks_queue_size | Integer | 2 | Number of workers performing repository event jobs. |
index_queue_size | Integer | 1 | Number of workers performing code search indexing jobs |
ldap_collaborators_base
|
String | LDAP search base for collaborators | |
ldap_collaborators_enabled
|
Boolean | false
|
LDAP authentication for collaborators |
ldap_collaborators_filter
|
String | LDAP search filter used when finding collaborators | |
ldap_domain_base
|
String | LDAP search base for users | |
ldap_email
|
String | LDAP account email field mapped to TeamHub email | |
ldap_encryption
|
String | plain
|
LDAP encryption. Allowed: plain , start_tls , simple_tls |
ldap_filter
|
String | LDAP search filter used when finding users | |
ldap_first_name
|
String | LDAP account first name field | |
ldap_groups
|
String | LDAP field defining users groups | |
ldap_groups_base
|
String | LDAP groups search base | |
ldap_groups_from_user
|
Boolean | false
|
LDAP users contain group information |
ldap_host
|
String | LDAP hostname | |
ldap_interface_max_connections | Integer | 10000 | Maximum connections for a child process until it is replaced with a new fork in the LDAP interface |
ldap_interface_max_idle | Integer | 10 | Maximum idle time, in seconds, for a child process after stopping serving requests until it is replaced with a new fork in the LDAP interface |
ldap_interface_max_servers | Integer | 32 | Maximum number of forked child processes in the LDAP interface |
ldap_interface_min_servers | Integer | 4 | Minimum number of forked child processes in the LDAP interface |
ldap_interface_timelimit | Integer | 30 | Maximum server-side time limit, in seconds, for a request in the LDAP interface |
ldap_last_name
|
String | LDAP account last name field | |
ldap_password
|
String | LDAP search password | |
ldap_port
|
String | LDAP port | |
ldap_short_name
|
String | LDAP account ID field mapped to TeamHub login | |
ldap_source
|
String | LDAP sync identifier | |
ldap_ssl_verify | Boolean | false | Defines whether to validate external LDAP host certificate |
ldap_user
|
String | LDAP search username | |
license_expire_notify
|
String | 30,14,7,3
|
Defines the intervals (number of days) before license expiration to notify instance admins through email. |
merge_queue_size | Integer | 2 | Number of workers performing merge jobs. |
merge_timeout | Integer | 120 | Timeout for code review merge in seconds. |
multipart_file_limit | Integer | 128 | Helix DAM only: The maximum number of parts with a filename a request can contain. Accepting too many parts can lead to the server running out of file handles. Affects how many files can be uploaded at once. See multipart_file_limit |
multipart_total_part_limit | Integer | 4096 | Helix DAM only: The maximum total number of parts a request can contain of any type, including both file and non-file form fields. Affects how many files can be uploaded at once. See multipart_total_part_limit |
password_expire_count
|
Integer | 0
|
Defines the number of old passwords that cannot be used again. Value of 0 allows reusing old passwords. |
password_expire_days
|
Integer | 0
|
Defines the maximum number of days a password can be used before it expires. Value of 0 means that passwords never expire. |
password_expire_notify
|
Integer | 7
|
Defines the number of days before password expiration to notify accounts. |
password_validation_entropy
|
Integer | -1
|
The password_validation_entropy configuration flag defines the minimum password entropy level required related to the email, short_name, first_name, last_name field values using the Levenshtein algorithm.
|
password_validation_format
|
String | /(?=.*[[:upper:]])(?=.*[[:lower:]])(?=.*[[:digit:]]).*/
|
Defines the password format requirements for account password validation. By default, password validation requires a minimum of one uppercase letter, one lowercase letter, and one digit. To remove the requirement for a specific password validation format, set password_validation_format to |
password_validation_range
|
String | 8..100
|
Defines the minimum and maximum length for account password validation. |
pilsner_timeout | Integer | 55 | Pilsner request timeout in seconds. |
redis_host
|
String | localhost
|
Redis hostname for Enterprise |
redis_password
|
String | Redis password | |
redis_port
|
Integer | 6379
|
Redis port |
repository_gc_queue_size | Integer | 1 | Number of workers performing garbage collection jobs. |
search_engine |
String |
null |
Supported value
|
Section: backups
This section groups Backups and restoration related settings.
Key | Type | Default | Description |
---|---|---|---|
keep
|
Integer | 30
|
How many backups to keep before oldest backup gets removed (Archival method only) |
s3_access_key
|
String | Amazon S3 access key for offline backups | |
s3_bucket
|
String | Amazon S3 bucket name for offline backups | |
s3_key_id
|
String | Amazon S3 key ID for offline backups | |
s3_region
|
String | Amazon S3 region for offline backups |
Section: docker_registry
This section groups TeamHubDocker Registry related settings.
Key | Type | Default | Description |
---|---|---|---|
backups | Boolean | false | Whether Docker backups are enabled |
backups_keep
|
Integer | 5
|
How many backups to keep before oldest backup gets removed |
log_level
|
String | warn
|
Log level for Docker service |
storage_driver | String | filesystem | Docker storage driver to use, see Docker Registry |
storage_settings | Object | Docker storage driver options, see Docker Registry storage driver on the Docker website |
Section: gconn
This section groups the Git Connector (Gconn) settings.
Key | Type | Default | Description |
---|---|---|---|
helix_user | String | null | Helix Core Server user of Git Connector |
host | String | null | Hostname of the server Git Connector is installed on |
https_enabled | Boolean | false | Defines whether https is enabled or disabled for Git Connector |
https_port | Integer | null | Https protocol port. |
ssh_enabled | Boolean | false | Defines whether SSH is enabled or disabled for Git Connector |
ssh_port | Integer | null | SSH protocol port |
user | String | null | OS user of the Git Connector |
Section: helix
This section groups Helix Core Server connection settings.
Key | Type | Default | Description |
---|---|---|---|
charset | String | utf8 | Character set encoding on the Helix Core Server. For example, utf8or none. |
p4port | String | null | The hostname or IP address and port for the Helix Core Server, in the form of: host:port |
password | String | null | Password or ticket for the Helix Core Server super user |
sync_interval | String | */5 * * * * | Interval to sync with the Helix Core Server. Set in Cron format, default is every 5 minutes |
user | String | null | An existing Helix Core Server user with super level privileges. This user must have unlimited ticket timeout |
Section: logging
This section groups TeamHub logging related settings.
Key | Type | Default | Description |
---|---|---|---|
logrotate_frequency
|
String | daily
|
Frequency of logrotate rotation |
logrotate_rotate
|
Integer | 30
|
Number of logrotate files to keep |
logrotate_size
|
Integer | Size of logrotate rotation. Does not rotate by size by default. | |
svlogd_num
|
Integer | 30
|
Number of SV log files to keep |
svlogd_size
|
Integer | 209715200
|
The maximum size when SV rotation should happen (200MB) |
svlogd_timeout
|
Integer | 86400
|
Number of seconds when SV rotation should happen (24 hours) |
Section: mongodb
This section groups TeamHub MongoDB database related settings, which are usually required in Enterprise or HA deployment for tools such as TeamHub Backups accessing MongoDB database.
Key | Type | Default | Description |
---|---|---|---|
backup_s3
|
Boolean | false
|
Defines whether MongoDB backups need to be taken offline to Amazon S3. Requires backups section configuration |
backups
|
Boolean | false
|
Defines whether TeamHub MongoDB backups are enabled |
password
|
String | MongoDB password | |
port
|
Integer | 4002
|
MongoDB port |
username
|
String | MongoDB username |
Section: nginx
This section groups TeamHub Nginx related settings.
Key | Type | Default | Description |
---|---|---|---|
admin_allowed_ips |
Array |
[] |
Limit access to the Admin user interface to specified IP addresses or CIDR (Classless Inter-Domain Routing). |
allowed_hosts |
Array |
[] |
Specify the hosts that can connect to TeamHub, this mitigates host header injection attacks.
|
cors_allowed_domains |
String or an array of strings |
"*" |
Cross-Origin Resource Sharing (CORS) controls the external domains that can be used with TeamHub.
|
csp_header |
String |
default-src 'self'; style-src 'self' 'unsafe-inline'; img-src * data: blob: |
Content-Security-Policy header. An empty value omits the header. To use the Content-Security-Policy header with the Safari browser, an additional connect-src policy directive is needed. For example, for the example.com domain:
|
enable_sslv3 |
Boolean |
false |
Whether SSLv3 should be enabled, see Poodle vulnerability |
keepalive_timeout |
Integer |
65 |
Number of seconds for keep-alive connection |
max_body_size |
String | 4G | Maximum size of client request body |
proxy_read_timeout |
Integer |
120 |
Number of seconds for reading a response from backend services |
proxy_send_timeout |
Integer |
120 |
Number of seconds for sending a request to backend services |
request_limit_burst |
Integer |
50 |
Number of requests a client can make over the rate specified in request_limit_rate |
request_limit_enable |
Boolean |
false |
Enable or disable request limiting. To learn more about rate limiting, see Rate Limiting with NGINX. |
request_limit_nodelay |
Boolean |
true |
Indicates whether to space out forwarding of queued requests |
request_limit_rate |
Integer |
20 |
Maximum number of requests to perform per second |
request_limit_whitelist |
Array |
[] |
List of IP addresses to exclude from rate limiting |
server_names |
String |
_ |
Server names nginx will listen on |
ssl_ciphers |
String |
See default nginx ciphers below [1] |
Specifies enabled ciphers in the format understood by the OpenSSL library |
ssl_protocols |
String |
TLSv1.2 TLSv1.3 |
SSL protocols to enable. |
worker_connections |
Integer |
1024 |
Number of Nginx simultaneous worker connections |
worker_processes |
Integer |
2 |
Number of Nginx worker processes to start |
[1] Default nginx ciphers:
ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305
Section: opensshp
This section groups OpenSSH related settings.
Key | Type | Default | Description |
---|---|---|---|
enable | Boolean | false | Whether the bundled OpenSSH is used or not, see OpenSSH. |
Section: p4search
Helix DAM only: This section groups related settings for the Elasticsearch instance used by Helix Search.
Key | Type | Default | Description |
---|---|---|---|
es_hosts | Array | [] | Array of Elasticsearch host hashes. Supported keys are: host, port, scheme, user, password. |
es_ssl_verify | Boolean | true | Defines whether to validate the Elasticsearch host certificate. |
es_index | String | null | Defines the Elasticsearch index name used by Helix Search. |
Section: pilsner
This section groups settings related to
Key | Type | Default | Description |
---|---|---|---|
helix_groups_exclude_regex |
String |
Names of groups to be excluded from mirroring between Helix Core Server and TeamHub, specified as a comma-delimited list of Ruby regular expressions, for example: ^swarm-group$ The specified groups do not appear in the TeamHub UI. Important
By default, TeamHub ignores all groups starting with HTH- and all legacy Perforce product groups in Helix Core Server, such as Swarm groups. |
|
helix_groups_include_regex |
String |
Names of groups to be included when mirroring between Helix Core Server and TeamHub, specified as a comma delimited list of Ruby regular expressions, for example: ^swarm-group$ The specified groups appear in the TeamHub UI. |
|
helix_timeout | Integer | 50 | Helix Core Server request timeout in seconds. |
helix_users_exclude_regex |
String |
|
Names of users to be excluded from mirroring between Helix Core Server and TeamHub, specified as a comma delimited list of Ruby regular expressions, for example: ^(user1|user2)$ The specified users do not appear in the TeamHub UI. |
helix_users_from_groups_exclude_regex |
String |
Names of groups to exclude users from when mirroring between Helix Core Server and TeamHub, specified as a comma delimited list of Ruby regular expressions, for example: ^perforce-group$ The users from the specified groups do not appear in the TeamHub UI. |
|
helix_users_from_groups_include_regex |
String |
|
Names of groups to include users from when mirroring between Helix Core Server and TeamHub, specified as a comma delimited list of Ruby regular expressions, for example: ^perforce-group$ The users from the specified groups appear in the TeamHub UI. |
helix_users_include_regex |
String |
Names of users to be included while mirroring between Helix Core Server and TeamHub, specified as a comma delimited list of Ruby regular expressions, for example: ^(user1|user2)$ The specified users appear in the TeamHub UI. |
|
host | String | localhost | Pilsner service hostname. |
port | Integer | 9292 | Pilsner service port. |
Section: postfix
This section groups TeamHub local Postfix MTA mailing settings.
Key | Type | Default | Description |
---|---|---|---|
masquerade_domain
|
String | Domain of the email key | Masquerade domain |
message_size_limit
|
Integer | 20000000
|
Max size of the message in bytes |
password
|
String | Password for SASL authentication | |
relay_host
|
String | Relay hostname | |
relay_port
|
Integer | 25 |
Relay port |
sasl_auth_enable
|
Boolean | false
|
Whether SASL authentication is enabled |
tls_auth_enable
|
Boolean | false
|
Whether TLS is used |
tls_ca_crt_bundle
|
String | TLS CA certificates file | |
user_name
|
String | Username for SASL authentication |
Section: puma_pilsner
This section groups TeamHub Puma Pilsner server related settings.
Key | Type | Default | Description |
---|---|---|---|
max_memory
|
Integer | 1000
|
Maximum total memory (MB) for Puma Pilsner when multiple workers are used |
max_threads
|
Integer | 4
|
Maximum size of worker's thread pool |
min_threads
|
Integer | 0
|
Minimum size of worker's thread pool |
worker_processes
|
Integer | 2
|
Number of Puma Pilsner worker processes to start |
Section: redis
This section groups Redis related settings.
Key | Type | Default | Description |
---|---|---|---|
password | string | Redis server password | |
port | Integer | 6379 | Redis server port |
Section: repos
This section groups TeamHub repositories related settings.
Key | Type | Default | Description |
---|---|---|---|
backups
|
Boolean | false
|
Defines whether TeamHub repository backups are enabled |
Section: unicorn_backend
This section groups TeamHub backend (APIs, TeamHub Admin) Unicorn server related settings.
Key | Type | Default | Description |
---|---|---|---|
backlog_socket | Integer | 64 | Unicorn socket backlog size |
worker_processes
|
Integer | 4
|
Number of Unicorn worker processes to start |
worker_timeout
|
Integer | 60
|
Number of seconds Unicorn worker times out |