[Other doc versions]
[Doc downloads]
This page describes Stash system properties that can be used to control aspects of the behaviour in Stash. System properties are contained in the stash-config.properties
file, in your Stash home directory.
Stash must be restarted for changes to become effective.
Default values for system values, where applicable, are specified in the tables below.
On this page:
Property | Description |
---|---|
audit.highest.priority.to.log=HIGH | Defines the lowest priority audit events that will be logged. Setting the value to HIGH will result in only HIGH level events being logged. NONE will cause no events to be logged. MEDIUM will only allow events with a priority of MEDIUM and HIGH to be logged. Refer to the levels for the various events. This does not affect events displayed in the Audit log screens for projects and repositories. |
audit.details.max.length=1024 | Defines the number of characters that can be can stored as details for a single audit entry. |
plugin.stash-audit.max.entity.rows=500 | The maximum number of entries a project or repository can have in the audit tables. This does not affect the data stored in the logs. |
plugin.stash-audit.cleanup.batch.size=1000 | When trimming the audit entries table this is the maximum number of rows that will be trimmed in one transaction. Reduce this size if you are having issues with long running transactions. This does not affect the data stored in the logs. |
plugin.stash-audit.cleanup.run.interval=24 | How often the audit tables will be checked to see if they need to be trimmed (in hours). This does not affect the data stored in the logs. |
Property | Description |
---|---|
plugin.auth-crowd.sso.enabled=false | Whether SSO support should be enabled or not. Regardless of this setting SSO authentication will only be activated when a Crowd directory is configured in Stash that is configured for SSO. |
plugin.auth-crowd.sso.session.validationinterval=3 | The number of minutes to cache authentication validation in the session. If this value is set to 0, each HTTP request will be authenticated with the Crowd server. |
plugin.auth-crowd.sso.session.lastvalidation=atl.crowd.sso.lastvalidation | The session key to use when storing a Date value of the user's last authentication. |
plugin.auth-crowd.sso.session.tokenkey=atl.crowd.sso.tokenkey | The session key to use when storing a String value of the user's authentication token. |
Property | Description |
---|---|
avatar.gravatar.default=mm | The fallback URL for Gravatar avatars when a user does not have an acceptable avatar configured. This may be a URL resource, or a Gravatar provided default set. |
avatar.max.dimension=1024 | Controls the max height and width for an avatar image. Even if the avatar is within the acceptable file size, if its dimensions exceed this value for height or width, it will be rejected. When an avatar is loaded by the server for processing, images with large dimensions may expand from as small as a few kilobytes on disk to consume a substantially larger amount of memory, depending on how well the image data was compressed. Increasing this limit can substantially increase the amount of heap used while processing avatars and may result in OutOfMemoryErrors. Value is in PIXELS. |
avatar.max.size=1048576 | Controls how large an avatar is allowed to be. Avatars larger than this are rejected and cannot be uploaded to the server, to prevent excessive disk usage. Value is in BYTES. |
avatar.temporary.cleanup.interval=1800000 | Controls how frequently temporary avatars are cleaned up. Any temporary avatars that have been uploaded are checked against their configured max age and removed from the file system if they are "too old". Value is in MILLISECONDS. |
avatar.temporary.max.age=30 | Controls how long a temporary avatar that has been uploaded is retained before it is automatically deleted. Value is in MINUTES. |
avatar.url.default=${avatar.gravatar.default} | Defines the fallback URL to be formatted into the avatar.url.format.http or avatar.url.format.https URL format for use when a user does not have an acceptable avatar configured. This value may be a URL or, if using Gravatar, it may be the identifier for one of Gravatar's default avatars. The default here falls back on the now-deprecated avatar.gravatar.default setting, which should ensure that value, if set, continues to work until it is removed in Stash 3.0. At that time, this default will become "mm". |
| Defines the default URL format for retrieving user avatars over HTTP. This default uses any G-rated avatar provided by the Gravatar service [http://www.gravatar.com] The following format parameters are available: %1$s – The user's e-mail address, MD5 hashed, or "00000000000000000000000000000000" if the user has no e-mail %2$d – The requested avatar size %3$s – The fallback URL, URL-encoded, which may be defined using "avatar.url.default" %4$s – The user's e-mail address, not hashed, or an empty string if the user has no e-mail. |
| Defines the default URL format for retrieving user avatars over HTTPS. This default uses any G-rated avatar provided by the Gravatar service [http://www.gravatar.com] The following format parameters are available: %1$s – The user's e-mail address, MD5 hashed, or "00000000000000000000000000000000" if the user has no e-mail %2$d – The requested avatar size %3$s – The fallback URL, URL-encoded, which may be defined using "avatar.url.default" %4$s – The user's e-mail address, not hashed, or an empty string if the user has no e-mail. |
Property | Description |
---|---|
changeset.diff.context=10 | Defines the number of context lines to include around diff segments in changeset diffs. |
These properties control how changesets are indexed when new commits are pushed to Stash.
Property | Description |
---|---|
indexing.max.threads=2 | Controls the maximum number of threads which are used to perform indexing. The resource limits configured below are not applied to these threads, so using a high number may negatively impact server performance. |
indexing.job.batch.size=250 | Defines the number of changesets which will be indexed in a single database transaction. |
indexing.job.queue.size=150 | Defines the maximum number of pending indexing requests. When this limit is reached, attempts to queue another indexing operation will be rejected. |
indexing.process.timeout.execution=3600 | Controls how long indexing processes are allowed to execute before they are interrupted, even if they are producing output or consuming input. The value is in SECONDS |
Database properties allow very specific configuration for your database connection parameters, which are set by Stash during database setup and migration, and allow you to configure a database of your own. We don't expect that you will edit these, except in collaboration with Atlassian Support.
Any other driver must be placed in WEB-INF/lib
in order to use the associated database.
Warning: jdbc.driver
and jdbc.url
are available to plugins via the ApplicationPropertiesService. Some JDBC drivers allow the username and password to be defined in the URL. Because that property is available throughout the system (and will be included in STP support requests), that approach should not be used. The jdbc.username
and jdbc.password
properties should be used for these values instead.
If none of the values below are specified in stash-config.properties
, then a provided HSQL database will be used.
Property | Description |
---|---|
jdbc.driver=org.hsqldb.jdbcDriver | The JDBC driver class that should be used by Stash to connect to the database. The default Stash database uses the file-based HSQL database, storing its data in the
|
jdbc.url=jdbc:hsqldb:${stash.home}/data/db;shutdown=true | This is the JDBC url that Stash will use to connect to the database. This should include the driver subprotocol (e.g., postgresql: ), the hostname, port and database that you will connect to. This string may vary depending on the database you are connecting to. Please seek specific examples for other databases from your database provider. |
jdbc.user=SA | This is the user that Stash will connect to the database with. The user will need to be able to create and drop tables and indexes, as well as read and write operations on the entire database schema defined in jdbc.url . |
jdbc.password= | The password that the user defined by jdbc.user will connect with. |
jdbc.ignoreunsupported=false | Allows using a given database, even though it is marked as UNSUPPORTED. This is not intended to be broadly documented, nor to be used generally. It is here as a support mechanism to override the supported database check in the event that it incorrectly blocks access to a database. |
These properties control the database pool. The pool implementation used is BoneCP. Documentation for these settings can be found at: http://jolbox.com/configuration.html
To get a feel for how these settings really work in practice, the most relevant classes in BoneCP are:
Property | Description |
---|---|
db.pool.acquireIncrement=2 | Defines the number of connections to open in a batch when open connections are almost exhausted for a given partition. |
db.pool.cache.statements=100 | Defines the number of statements to cache. |
db.pool.connection.timeout=15 | Defines the amount of time the system will wait when attempting to open a new connection before throwing an exception. The system may hang, during startup, for the configured number of seconds if the database is unavailable. As a result, the timeout configured here should not be generous. Value is in SECONDS. |
db.pool.idle.maxAge=30 | Defines the maximum period of time a connection may be idle before it is closed. Generous values should be used here to prevent creating and destroying many short-lived database connections (which defeats the purpose of pooling). Value is in MINUTES. |
db.pool.idle.testInterval=10 | Defines the amount of time a connection may be idle before a test query is executed by the pool. This helps prevent connections from being closed by the database server due to inactivity. Value is in MINUTES. |
db.pool.partition.connection.maximum=20 | Defines the maximum number of connections that may be open in a given partition. |
db.pool.partition.connection.minimum=4 | Defines the minimum number of connections open for a given partition. Each partition will open this many connections on startup. That means db.pool.partition.connection.minimum x db.pool.partition.count = initial connection count. |
db.pool.partition.connection.threshold=10 | Defines the threshold as a percentage of the maximum connections that each partition will attempt to keep available at all times. If the number of available connections drops to or below the threshold, acquireIncrement connections will be opened until the partition is above it again. Warning: Be careful to take this number into account when setting the minimum and maximum counts. For example, if the maximum is 30 and the minimum is 5 and the threshold is 20 (20%), 5 is not 20% of 30, so immediately after it is created the partition will open additional connections to get above the threshold. Effectively, that would mean that the "minimum" per partition is 10 (5 + 5 acquireIncrement ), or 40 connections at all times. |
db.pool.partition.count=4 | Defines the number of different connection partitions to use. This value is used to decrease lock contention, because each partition locks individually. The recommended setting is 3 or 4, but in servers with heavy load and many short- lived requests, performance may be improved by using a higher value. |
db.pool.threads=4 | Defines the number of helper threads which will be used by the pool to cleanup and release connections back into the pool. Setting a value of 0 disables this feature, which means the executing thread will perform cleanup and release itself. A non-zero value results in a pool of helpers which process connections out of a holding queue. When a thread "closes" a connection, that thread is allowed to continue executing and the connection is placed in the queue. One of the helper threads then performs final cleanup to prepare the connection to be returned to the pool. |
Property | Description |
---|---|
http.download.raw.policy=Smart | Controls the download policy for raw content. Possible values are:
|
These properties control the number of threads that are used for dispatching asynchronous events. Setting this number too high can decrease overall throughput when the system is under high load because of the additional overhead of context switching. Configuring too few threads for event dispatching can lead to events being queued up, thereby reducing throughput. These defaults scale the number of dispatcher threads with the number of available cpu cores.
Property | Description |
---|---|
event.dispatcher.core.threads=0.8*cpu | The minimum number of threads that is available to the event dispatcher. The cpu variable is resolved to the number of cpus that are available. |
event.dispatcher.max.threads=cpu | The maximum number of event dispatcher threads. The number of dispatcher threads will only be increased when the event queue is full and max.threads has not been reached yet. |
event.dispatcher.queue.size=4096 | The number of events that can be queued. When the queue is full and no more threads can be created to handle the events, events will be discarded. |
event.dispatcher.keepAlive=60 | The time a dispatcher thread will be kept alive when the queue is empty and more than core.threads threads are running. Value is in SECONDS. |
Controls the thread pool that is made available to plugins for asynchronous processing.
Property | Description |
---|---|
executor.max.threads=100 | Specifies the maximum number of threads in the thread pool. When more threads are required than the configured maximum, the thread attempting to schedule an asynchronous task to be executed will block until a thread in the pool becomes available. |
executor.keepAliveTime=60 | Controls how long idle threads are kept alive. Threads idle for more than this time will be terminated. Value is in SECONDS and must be >= 1. If 0 or a negative value is used, a default value of 1 will be configured. |
Feature properties control high-level system features, allowing them to be disabled for the entire instance. Features that are disabled at this level are disabled completely. This means that instance-level configuration for a feature is overridden. It also means that a user's permissions are irrelevant; a feature is still disabled even if the user has the SYS_ADMIN permission.
Property | Description |
---|---|
feature.auth.captcha=true | Controls whether to require CAPTCHA verification when the number of failed logins is exceeded. If enabled, any client who has exceeded the number of failed logins allowed using either the Stash web interface or the Git hosting interface will be required to authenticate in the Stash web interface and successfully submit a CAPTCHA before continuing. Setting this to false will remove this restriction and allow users to incorrectly authenticate as many times as they like without penalty.
Warning: It is STRONGLY recommended you keep this setting enabled. Disabling it will have the following ramifications:
|
feature.forks=true | Controls whether repositories can be forked. This setting supersedes and overrides instance-level configuration. If this is set to false, even repositories which are marked as forkable cannot be forked. |
feature.public.access=true | Public access to Stash allows unauthenticated users to be granted access to projects and repositories for specific read operations including cloning and browsing repositories. This is normally controlled by project and repository administrators but can be switched off system wide by setting this property to false. This can be useful in highly sensitive environments. |
Property | Description |
---|---|
| When |
| Controls Hibernate's JDBC batching limit, which is used to make bulk processing more efficient (both for processing and for memory usage). |
| Used to enable Hibernate SQL logging, which may be useful in debugging database issues. This value should generally only be set by developers, not by customers. |
Property | Description |
---|---|
| Controls the maximum number of changesets to retrieve when retrieving attributes associated with changesets of a pull-request. This value should be between 50 and 1000 as Stash will enforce an lower bound of 50 issues and an upper bound of 1000 issues. |
| Controls the maximum number of issues to request from JIRA. This value should be between 5 and 50 as Stash will enforce a lower bound of 5 issues and an upper bound of 50 issues. |
| The connection timeout duration in milliseconds for requests to JIRA. This timeout occurs if the JIRA server does not answer. e.g. the server has been shut down. This value should be between 2000 and 60000 as Stash will enforce a lower bound of 2000ms and an upper bound of 60000ms. Value is in MILLISECONDS. |
| The socket timeout duration in milliseconds for requests to JIRA. This timeout occurs if the connection to JIRA has been stalled or broken. This value should be between 2000 and 60000 as Stash will enforce a lower bound of 2000ms and an upper bound of 60000ms Value is in MILLISECONDS. |
Property | Description |
---|---|
| The maximum number of changes executed against a particular Liquibase database before a commit operation is performed. Very large values may cause DBMS to use excessive amounts of memory when operating within transaction boundaries. If the value of this property is less than one, then changes will not be committed until the end of the change set. |
Logging levels for any number of loggers can be set in the stash-config.properties
file using the following format:
logging.logger.<name>=<level>
For example, to configure all classes in the com.atlassian.stash package to DEBUG level:
logging.logger.com.atlassian.stash=DEBUG
To adjust the ROOT logger, you use the special name ROOT (case-sensitive):
logging.logger.ROOT=INFO
Property | Description |
---|---|
| Controls the maximum allowed size of a single comment in characters (not bytes). Extra characters will be truncated. |
| Controls the maximum allowed size of a single description in characters (not bytes). Extra characters will be truncated. |
| Controls whether mentions are enabled |
| Controls the maximum number of allowed mentions in a single comment |
These properties control the maximum number of objects which may be returned on a page, regardless of how many were actually requested by the user. For example, if a user requests Integer.MAX_INT branches on a page, their request will be limited to the value set for page.max.branches
.
This is intended as a safeguard to prevent enormous requests from tying up the server for extended periods of time and then generating responses whose payload is prohibitively large. The defaults configured here represent a sane baseline, but may be overridden by customers if necessary.
Property | Description |
---|---|
| Maximum number of branches per page. |
| Maximum number of changes per page. Unlike other page limits, this is a hard limit; subsequent pages cannot be requested when the number of changes in a changeset exceeds this size. |
| Maximum number of changesets (commits) per page. |
| Maximum number of segment lines (of any type, total) which may be returned for a single diff. Unlike other page limits, this is a hard limit; subsequent pages cannot be requested when a diff exceeds this size. |
| Maximum number of directory entries which may be returned for a given directory. |
| Maximum number of file entries which may be returned for a recursive listing of a directory. A relatively high number as this is used by the file finder which needs to load the tree of files upfront. |
| Maximum number of groups per page. |
| Maximum number of changesets which may be returned from the index when querying by an indexed attribute. For example, this limits the number of changesets which may be returned when looking up commits against a JIRA issue. |
| Maximum number of projects per page. |
| Maximum number of repositories per page. |
| Maximum length for any line returned from a given file when viewing source. This value truncates long lines. There is no mechanism for retrieving the truncated part short of downloading the entire file. |
| Maximum number of lines which may be returned from a given file when viewing source. This value breaks large files into multiple pages. |
| Maximum number of tags per page. |
| Maximum number of users per page. |
| The size of the page Stash should use when scanning activities. |
| The number of pages of activities Stash should scan before giving up. |
Property | Description |
---|---|
| Controls how long a password reset token remains valid for. Default period is 72 hours. Value is in MINUTES. |
Property | Description |
---|---|
| Controls timeouts for external processes, such as Git and Hg. The idle timeout configures how long the command is allowed to run without producing any output. The execution timeout configures a hard upper limit on how long the command is allowed to run even if it is producing output. Values are in SECONDS. Using 0, or a negative value, disables the timeout completely. USE AT YOUR OWN RISK!
|
Property | Description |
---|---|
| Defines the number of context lines to include around diff segments in pull request diffs. By default, Git only includes 3 lines. The default is 10, to try and include a bit more useful context around changes, until the ability to "expand" the context is implemented. |
| Defines the maximum number of changesets per type (either added or removed) to display in a rescope activity. |
| Defines the absolute maximum number of changesets that will be evaluated when attempting to determine, for a given rescope activity, which changesets were added to or removed from a pull request. Adjusting this setting can have significant memory footprint impact on the system. It is not recommended to be changed, but the option is provided here to support unique use cases. |
| Defines the maximum number of threads to use for precalculating rescope details. These threads perform the requisite processing to determine the commits added and removed when a pull request is rescoped, where most rescopes do not add or remove any commits. Such "dead" rescopes are deleted during processing. The primary goal is to ensure all details have already been calculated when users try to view a pull request's overview. |
| Defines the maximum number of threads to use when processing comment drift for a pull request during rescope. Higher numbers here do not necessarily mean higher throughput! Performing comment drift will usually force a new merge to be created, which can be very I/O intensive. Having a substantial number of merges running at the same time can significantly reduce the speed of performing comment drift. |
Property | Description |
---|---|
| Controls the maximum allowed size of a readme file to parse. Value is in BYTES. |
These properties define concurrent task limits for the ThrottleService, limiting the number of concurrent operations of a given type
that may be run at once. This is intended to help prevent Stash from overwhelming a server machine with running processes.
The hard, machine-level limits these are intended to prevent hitting are very OS- and hardware-dependent, so they may
need to be tuned by customers. These defaults are finger-in-the-wind guesstimates (which so far have worked well).
Additional resource types may be configured by defining a key with the format throttle.resource.<resource-name>
.
When adding new types, it is strongly recommended to configure their ticket counts explicitly using this approach.
Property | Description |
---|---|
| Limits the number of SCM commands, such as: "git diff"; "git blame"; or "git rev-list", which may be running concurrently. This limit is intended to prevent the operations which support the UI from preventing push/pull operations from being run. |
| Controls how long threads will wait for SCM commands to complete when the system is already running the maximum number of SCM commands. Value is in SECONDS. |
| Limits the number of SCM hosting operations, meaning pushes and pulls over HTTP or SSH, which may be running concurrently. This is intended primarily to prevent pulls, which can be very memory-intensive, from pinning a server's resources. There is limited support for mathematical expressions; +,-,*,\ and () are supported. You can also use the |
| Controls how long threads will wait for SCM hosting operations to complete when the system is already running the maximum number of SCM hosting operations. Value is in SECONDS. |
| Controls how long a warning banner is displayed in the UI after a request is rejected due to excessive load. Value is in MINUTES. Using 0, or a negative value, disables displaying the banner.
|
See Scaling Stash for Continuous Integration performance for more information.
Property | Description |
---|---|
plugin.stash-scm-cache.expiry.check.interval=300 | Controls how frequently expired caches are checked and deleted from disk. Value is in SECONDS. |
plugin.stash-scm-cache.minimum.free.space=1073741824 | Controls how much space needs to be available on disk (specifically under <STASH-HOME>/caches) for caching to be enabled. This setting ensures that the cache plugin does not fill up the disk. Value is in BYTES. |
plugin.stash-scm-cache.refs.enabled=false | Controls whether ref advertisement operations are cached. |
plugin.stash-scm-cache.refs.ttl=60 | Controls how long the caches for ref advertisements are kept around when there no changes to the repository. Caches are automatically invalidated when someone pushes to a repository or when a pull request is merged. Time is in SECONDS. |
plugin.stash-scm-cache.upload-pack.enabled=true | Controls whether clone operations are cached. |
plugin.stash-scm-cache.upload-pack.ttl=3600 | Controls how long the caches for clone operations are kept around when there no changes to the repository. Caches are automatically invalidated when someone pushes to a repository or when a pull request is merged. Time is in SECONDS. |
Property | Description |
---|---|
| Defines the default path to the Git executable. On Windows machines, the .exe suffix will be added to the configured value automatically if it is not present. In general, "git" should be an acceptable default for every platform, here, assuming that it will be available in the runtime user's PATH. |
| Defines the path to the Git libexec directory (containing the git-core directory). This path is hard-coded into the Git executable and is used for forking processes like git-http-backend. If this value is set, Stash will directly fork out those processes. This eliminates an unnecessary fork (git -> git-http-backend) and may improve scalability. |
| Defines the buffer size in bytes which is used when marshaling data between the Git process and the HTTP socket. |
| Defines the buffer size in bytes which is used when marshaling data between the Git process and the SSH socket. |
| Defines the idle timeout for push/pull processes, applying a limit to how long the operation is allowed to execute without either producing output or consuming input. The default value is 30 minutes. This value is in SECONDS. |
| Defines the execution timeout for push/pull processes, applying a hard limit to how long the operation is allowed to run even if it is producing output or reading input. The default value is 1 day. This value is in SECONDS. |
| Defines whether copy and/or rename detection should be performed. By default, both rename and copy detection are performed. Only files modified in the same commit are considered as rename or copy origins, to minimize overhead. The possible settings are:
When using When copy and/or rename detection is enabled |
| Defines the threshold, as a percentage, for a file to be detected as a rename or a copy. This setting is only applied if copy and/or rename detection is enabled. The default threshold applied is 50% similarity (defined in Git itself). Git diff and Git diff-tree do not honor 100 (identical files only) for the threshold. They ignore the threshold and apply the default 50% threshold instead. A configured threshold of 100 will be applied as 99. Similarly, a configured threshold that is 0, or negative, will be applied as 1. |
| Defines the maximum number of characters that can be added to a single environment variable. Different operating systems (and even different versions of the same operating system) have different hard limitations they apply to environment variables. This default is intended to be low enough to work on all supported platforms out of the box, but still high enough to be usable. It is configurable in case it proves to be too high on some platform. |
| Defines whether conflicted files should be added to the index using Git Note: This value has no effect on real pull request merges. It is only applied during automatic merges, for producing a pull request's change tree and diff. |
| Defines the maximum amount of time any command used to perform a merge to support the "merge" diff mode is allowed to execute or idle. Because the commands used generally do not produce output, there is no separate idle timeout. This value is in SECONDS. |
| Defines the maximum amount of time any command used to merge a pull request is allowed to execute or idle. Because the commands used generally do not produce output, there is no separate idle timeout. This value is in SECONDS.
|
Property | Description |
---|---|
| Controls how long a warning banner is displayed in the UI after a request is rejected due to excessive load. Value is in MINUTES. Using 0, or a negative value, disables displaying the banner. |
| Controls how long requests need to be queued before they cause a warning banner to appear. Value is in SECONDS. Using 0, or a negative value, disables displaying the banner.
|
Property | Description |
---|---|
| Controls timeouts for establishing an SMTP connection and sending an e-mail. Shorter timeouts should be applied for when sending test e-mails, as the test occurs in user time. Values are in SECONDS. |
| Controls how frequently logs will go to the standard log file about mail sending errors. All errors are logged to the Value is in SECONDS |
| Controls how long Stash will wait before retrying to send a message if an error occurs. Value is in SECONDS |
| Controls the number of threads to use for sending emails. Setting this to a higher value will put greater load on your mail server when Stash generates a lot of emails, but will make Stash clear its internal queue faster. |
| Controls the maximum allowed size of a single mail message, which is the sum of the subject and body sizes. Value is in BYTES. |
| Controls the maximum allowed size for the mail queue (any new message will be rejected if the mail queue reaches that size). Value is in BYTES. |
Property | Description |
---|---|
| Controls timeouts for all SSH commands, such as those that service Git and hg operations over SSH. The idle timeout configures how long the command is allowed to run without writing any output to the client. For SCM commands, the plugin.*.backend.timeout.idle properties defined above will be applied to the underlying process. The default value is 1 day. The value is in SECONDS. |
See Configuring syntax highlighting for file extensions for more information.
Property | Description |
---|---|
syntax.highlighter.<language>.executables=exe1,exe2
| Controls the language highlighter used for a given set of hashbang executable. The |
syntax.highlighter.<language>.extensions=ext1,ext2 | Controls the language highlighter used for a given set of file extensions. The <language> refers to the highlighter key defined by highlight.js. |