System configuration settings

You can use a variety of settings to configure your Management Console. You can find these settings on the Administration > System page.

When you click Administration > System, the system displays a list of settings. Click the name of a system setting to display an edit panel for the setting.

Note: For system settings that take numeric values, the Management Console accepts any value that consists of one or more integers (0 through 9). Numeric-grouping characters, such as commas (,), decimals (.), and other noninteger separators, are not supported.

The panel includes the following buttons:

The following table describes the available settings.

Setting

Description

Account Lockout Decay Default: 60 minutes. After this amount of time, the system discards the last failed login attempt. If set to a negative value, failed logins are not discarded.
Account Lockout Max Attempts Default: 3. The number of consecutive failed login attempts required before an account is locked. If 0, account lockout is disabled.
Account Lockout Reset Timer Default: 120 minutes. Minimum: 5 minutes. The amount of time required before a user is permitted to attempt to log in again after being locked out. If set to a negative value, the lockout never expires: an administrator must reset the user to allow them to attempt to log in again.
Alert Email Limiting Sets the maximum number of alert emails the system sends over the specified number of minutes. For example, the value 10/60 sets the maximum to 10 messages per hour. The default value of 0/0 is interpreted by the system as no limit on messages.
Apply inlined steps container environment Default: No. If Yes, applies the environment of the project or library that contains an inlined step.
Apply server environment last Default: No. If Yes, applies the server environment for the step last. The server environment is applied after the step environment or project environment, if these environments are specified.
Audit Maximum String Length Default: 128 (characters). Controls how much information can be recorded for a DETAILED change. If a string value exceeds this number of characters, then a cryptographic hash is stored instead of the original value in an effort to conserve storage space. For fields that contain sensitive information, such as passwords, the cryptographic has is used regardless of the string length.
Audit Policy Determines how much audit logging is done.
NONE
No auditing information is recorded.
SECURITY
Only security-related are recorded. Examples: access group creation and user session activity.
BASIC
This is the default setting. It is also used if there is an invalid Audit Policy value. Only minimal information is recorded, such as user, object type, uuid, and action.
DETAILED
Records detailed information about what properties changed, including the old value and the new value. Not all objects can provide this information. For those that cannot, there is no difference between BRIEF and DETAILED policy. The Audit Max String Length system configuration setting can be used to limit the amount of data stored.

Auto-Logoff Minutes

The system can automatically log off users who are idle. This setting specifies the number of minutes of idle time that must pass before the system logs off a user. When the setting is 0, the system does not automatically log off users.

AutoClean Audit Log Days

AutoClean Error Log Days

AutoClean Info Log Days

AutoClean Warning Log Days

These values set a maximum number of days that each category of entry remains in the audit log; older entries are automatically deleted. If the value is 0, the system never deletes entries of that category. Because string values evaluate to 0 as integers, you can use a value such as "Never" instead of 0.

Build Cancel Check Frequency

Specifies how often the system checks for build cancellation requests, in terms of seconds between the checks.

Console Port

Port number that the web server uses to listen for Build Forge requests.

Console URL

URL that the web server uses to listen for Build Forge requests.

Must be set if the console is running on a port other than 80. If set, overrides the default console URL with the value. It takes the form <protocol>://<hostname>[:<port>]. Example: http://myHost:81.

Continue Step Parts On Fail Determines the run behavior of multiple commands parts in the same step. When set to the default of No, a failed command part in the step causes the step to fail. When set to Yes, a failed command part does not cause the step to fail. You can run the other commands part in the step. About command part, please refer to knowledge center "How the system splits a step into parts" (Developing > Working with steps > Controlling execution flow > How steps run).
Create Missing Paths Default: No. If yes, creates paths for projects if the path is not already present.
Database Size Threshold Threshold of database size at which the console will send a notice. Default: 2G.

Note that UI performance slows down as the threshold is approached. Performing a database cleanup or increasing the threshold size restores performance.

Database Size Threshold Notification User name or Notification Group to which email is sent if Database Size Threshold is reached. If a user name is used, the address in the Email field for the user is used. See Administration > Users.
Date Once Determines whether the .date command value is set once per job or once per step. The behavior depends on the value assigned, as follows:
  • No: This is the default value. The .date command value is set once per step. Each step re-evaluates the .date value using the agent machine's time zone. The agent provides the value. Restarts maintain the .date value. They are re-evaluated just like the initial run. The same variable would have a different value for each step where it is used, because the .date value is re-interpreted for each step.
  • Yes: The current .date command value is set once per job. The date value is produced using the engine host's time zone rather than the agent's time zone. Restarts maintain the .date value.

Use Yes when you use an environment variable that contains .date in email notifications, such as the .email command or notification templates. The environment variables used in the email then use the engine’s time zone.

Default Agent Port Sets the default port number used for making connections to agents.
Default Import Class Class to use if an imported project has no defined class or it has a defined class that does not exist. Default: Production.
Disable Authentication for XML Feeds Determines whether RSS data feeds are authenticated.
Enable Quickstart Default is no: all projects show the following icon: Quickstart icon. When you click the project, all variables included for the project are checked for variables of type Must Change. The project is started if it does not contain a Must Change variable. If the project contains a Must Change variable, then the project does not start, a dialog describes why, and the icon changes to this icon: Quickstart disabled icon.
Note: Only variables defined for the project are checked. Variables defined for steps in the project are not checked. See also Project variable changes made when starting a job.

If set to YES, the Projects page checks all environments for all projects on the page to determine if any variable is of type Must Change. Projects that are eligible to be started immediately indicate it with this icon: Quickstart icon. This was the default behavior until version 7.1.1.1.

Hard Run Limit Default: No. If Yes, the system launches a scheduled build of a project if its launch does not violate the project's Run Limit setting. If No, the system ignores the project's Run Limit setting for scheduled builds.

Import Default Secure Access Group

Specifies a default access group for imported projects when the Import with Secure Access setting is set to Y.

Import Insecure Default Access Group Specifies a default access group for imported projects when the Import with Secure Access setting is set to N. The default group is used only when the import file lacks an access group.

Import with Secure Access

When set to Y, the system assigns the default access group listed in the preceding setting to imported data objects. This overrides any access group specified in the XML file you are importing, so that users cannot override security by importing data. When set to N, the system honors any access group settings in imported files.

Inherit Tag

When set to Yes, causes jobs that are launched via a chain to use the same job tag as their caller. If BUILD_15 of project MasterProject calls project ComponentProject, then the job tag (and the job directory name) for that run of ComponentProject becomes BUILD_15.
Note: The called project always inherits the original tag of the caller; if the caller's tag changes during the run, as a result of a .retag command for example, the called project still gets the tag that the caller started with.

Invalid Relative Dir Characters

Sets the characters that the system will change into underscores if used in project names.

LASTRUN Format

Enter the value for the format for the BF_LASTRUN environment variable, using date format characters as defined for the .date command (see .date ).

License Server

The license server hostname. It is set during installation. Example: myhost.mycompany.com. The value may include a port number. Example: myhost.mycompany.com:80. To change the license server, see Changing the license server for the Management Console.

Link Debug Mode

When set to Yes, jobs that have adaptor links defined for them run a test of the link instead of running the associated project. The job output contains a single step, which contains output from the adaptor. The data is useful when you are troubleshooting your adaptor interfaces.

Note: You can set debugging for an individual adaptor link by setting the State for the adaptor link to Debug. The state takes precedence over the Link Debug Mode setting.

Link Manual Jobs

Determines whether the system runs adaptors through adaptor links when you quickstart a project manually rather than run it from the scheduler.

The link check may produce additional output in the BOM for the job.

If set to N, the link is not checked or run when the job runs.

Max Console Procs

Sets the maximum number of processes the console runs at one time. Use as a general throttle on console activity. The system manages processes by storing an ID for each process in the database and checking the total before launching a new external process. Make sure this value is greater than your Run Queue Size setting by at least 5; otherwise the system cannot run enough processes to support the run queue.

Max Inline Depth

Controls the number of levels the system allows for inlining of projects, so that projects cannot be infinitely nested. The default value is 32. If the value is set to 0, the system uses 32. When the system reaches the inline limit, an inlined project that would exceed the limit does not get run, and its steps do not get inserted in the containing project. A message is written to the system messages list: "inline abandoned."

Max simultaneous server tests

Specifies how many server tests can be run at once. Depending on your system resources, running too many server tests at one time can severely slow or lock up the console.

Max Simultaneous Purges

Controls how many purges can run simultaneously. You can purge as many builds as you like, but no more builds than the value in Max Simultaneous Purges will be simultaneously deleted. Default: 20

Maximum Refreshes Maximum number of times that a page refreshes automatically. Default: 50

Override Class when Chaining

Determines whether the system replaces a chained project's class with the class of its caller. The default value of Y causes the system to override the chained project's class and use the caller's class instead.

Password Expiration Days

Sets the number of days before users whose passwords are set to expire have to change their passwords. When this time expires, the relevant users are required to change their passwords on next login.

Password Format

Specifies the requirements for user passwords using a format string of six fields separated by periods:
length.char_types.upper.lower.numeric.special

Here is an example: 5.2.u1.l1.n1.s1. This example is explained below.

The first two fields specify the following:

  • Minimum password length (characters)
  • Minimum number of character types to use (an integer ranging from 1 to 4) in the four remaining fields

The remaining fields specify a character type and frequency requirement. Each field includes a type and a number.

  • Type: one of u (uppercase), l (lowercase), n (number), or s (special). Uppercase (U, L, N, S) indicates that the character is required. Lower case (u, l, n, s) indicates that the character is optional.
  • Number: for required, indicates the number of characters of this type that are required. For optional, indicates the number of characters of this type that are required if any are used.

The types are as follows:

  • U or u to indicate uppercase characters. This includes all characters that are considered a letter in their respective locales, but are not lowercase. Specifically, this includes characters that are uppercase, title-case, or any letter in single-case languages (such as Chinese).
  • L or l to indicate lowercase characters. This includes all characters that are considered lower case in their respective locales.
  • N or n to indicate numeric characters. This includes any character that is considered a digit in its respective locale.
  • S or s to indicate special characters. Any character that does not fit in the previous three categories. It includes all characters that are neither a letter nor a digit.

Example: the string 5.2.u1.l1.n1.s1 indicates the following password requirements:

  • At least 5 characters long
  • Must include characters from a minimum of two of the four categories (uppercase, lowercase, numeric, special).
  • For each type, one character of the type qualifies as a match to count toward the requirement.

Passwords such as abC1x and Abc2% would qualify.

Pause Build Forge Engine

When set to Y, the system completes any current jobs and then pauses the engine. Set it to N to return to normal operation.

Public Hostname

When set, the system substitutes the value of this setting for the server host name in the CONSOLEHOST variable in notification templates.

Purge Check Time

Sets the frequency with which the system checks for jobs to purge, in terms of minutes between checks.

QuickReport Public dir The file system location of the public report designs.

In 7.1, use this system setting to specify the fully qualified location to public reports. Your report designs must be in this directory to automatically migrate them.

In earlier releases, the default file location (../../reports/public) is relative to the application server installation directory, for example: <bfinstall>/Apache/tomcat/webapps/quickReport.

QuickReport Temp dir In 7.1, use this directory to specify a fully qualified directory on the same host as the services layer component. The services layer uses this working directory to list the report designs that have been successfully migrated to the database.

In earlier releases, this directory was used to temporarily store Quick Report report designs before they were saved to the public or private directory on the file system.

QuickReport Users dir The file system location of the private report designs.

In 7.1, use this system setting to specify the fully qualified location to private reports. Your report designs must be this directory to automatically migrate them.

In earlier releases, the default file location (../../reports/users) for private reports is relative to the application server installation directory, for example: <bfinstall>/Apache/tomcat/webapps/quickReport.

Reload Language Packs Default: No. If set to Yes, the console reloads its language packs upon restart and resets this value to No. No longer necessary starting in version 7.0.1.

Reset Adaptor Templates

Use this setting to reset the adaptor templates (to copy changes from an update into your configuration). To use it, set the value to "Yes", and then wait one minute. The system resets the templates and then sets the value back to No.

Reset Server Job-Count

Use this setting (Yes) to simultaneously reset the job count (BF_JOBS) for all servers to zero. The reset occurs when the manifest check interval runs. (The default time is every 10 seconds.)

After BF_JOBS has been reset for all servers, the Reset Server Job-Count value reverts back to No (the default).

Restart Report Migration Default: No. In 7.1, if you want to start migration without restarting the services layer component, set this value to Yes.
Run Chain Links Controls whether a launched chain project also launches any attached adaptor links.

Run Queue Size

This value limits the number of jobs the system attempts to run at once. When the number of runs in the queue equals or exceeds this number, the system stops moving runs from the Wait queue to the Run queue until the number of jobs drops below this value. If you change your Run Queue Size, check the Max Console Pros setting, which should be greater than the Run Queue Size by at least 5.

Save Start Environ

Controls the default value of the "Save Env" check box on the manual start page for a project. When this setting is Y, the box defaults to checked; otherwise, the box defaults to unchecked. The "Save Env" check box, when checked, causes any changes you make to the environment variables on the Start Page to be saved to the environment records in the database, so that future runs default to those values.

Server Env Before Chain

Determines whether the system sets a step's server environment before (Y) or after (N) setting the chaining project's project environment within the step. The variables in the second environment processed override those in the first environment. The default value is Y, indicating the chaining project's environment is processed second and overrides the step's server environment.

Server Retries

Sets how many times the system attempts to allocate a step to a server before it quits and fails the step, when the server matching all of the selectors conditions are found.

Server Test Frequency

Used together with the number of enabled servers to determine how frequently to test and refresh the manifest data for servers. The default is 120 minutes (2 hours). A value of 0 means do not check servers.

During these checks, the system contacts all enabled servers to verify that:

  • The servers are still reachable
  • The login information for the servers is correct
  • The manifest data for the servers is current

Server tests are performed at a minimum of one server per minute. That rate increases if the number of servers is much larger than this setting.

The system distributes the testing evenly over the interval. Examples:

  • You have 120 servers and the interval is set to 120 minutes. The system attempts to test one server per minute (120 servers / 120 minutes).
  • You have 12,000 servers and the interval is set to 1200 minutes. The system attempts to test 10 servers per minute.
  • You have 10 servers and the interval is set to 120 minutes. One server per minute is checked. A server will be checked as many as 12 times during the refresh interval in this scenario.

Manual server tests started from the console take precedence over these automated tests.

The complexity of a server's collector can affect throughput. A collector that performs many manual commands to collect data can require more than a minute to complete.

Server Usage Connect Timeout

Sets the number of seconds after creating an agent connection that the Management Console waits for the connection to open before failing the step.

Sets the timeout value for an existing connection to an agent. Agents are designed to contact the Management Console every 15 seconds. If no contact is made during a timeout period, the agent may have stopped or there might be network communication issues. The step fails if this value is exceeded.

Services layer authentication servlet URL

When set, will override the programmatically constructed URL to the services layer authentication servlet.

If you are using an alias or a non-default port, then this setting will need to be updated using the following format: http://server:port/rbf-services/AuthServlet

SMTP Server

Sets the computer to use as an SMTP server when sending email notifications.

The default setting is localhost.

SSO Remote User Default: No. If Yes, allows single sign-on remote user connections via standard web server authentication.

Stack BuildForge Env Variables

The system normally changes the name of BF_ variables that are passed down to a chained project to BF_CALLER_; this setting determines whether the system stacks the naming when chaining goes more than one level deep. The default value is N. When the setting is changed to Y, the BF_TAG variable derived from a calling project two levels deep receives the name BF_CALLER_CALLER_TAG.

Step Max Retries Controls how many times a step attempts to connect to an agent if the first attempt fails. The step fails if it does not connect in the specified number of retries.

Store User Authentication Locally

Determines whether the system caches LDAP/Active Directory user authentication information (in encrypted form). The default value is Yes. The system is only relevant when you use LDAP/Active Directory authentication. When the setting is Yes, the system caches user authentication information in encrypted form and can use it with the _USE_BFCREDS and _USE_BFCREDS_DOMAIN special variables (which apply user authentication to servers). You may choose to turn off caching by changing the value to No; however, if you do, the system cannot use the _USE_BFCREDS and _USE_BFCREDS_DOMAIN special variables to use the user's credentials when logging into a server.

System Alert Email

The system sends alert email messages to the address defined by this setting.

The default is root@localhost. The following email address formats are supported. Username is the email user name. Name is an arbitrary string, usually a given name in some form.
username@host.com
name username@host.com
name "<username@host.com>"
name <username@host.com>
name "username@host.com"

To send to multiple addresses, separate them with commas (,) or semicolons (;).

System Alert Source

When the system sends alert email messages, it uses the address defined in this setting as the sender.

The default is root@localhost. The following email address formats are supported. Username is the email user name. Name is an arbitrary string, usually a given name in some form.
username@host.com
name username@host.com
name "<username@host.com>"
name <username@host.com>
name "username@host.com"

System Wide Login Message

Allows you to define a message to be displayed above the login form.

System Wide User Message

Allows you to define a message to be displayed at the top of each page, just below the navigation buttons.

Tag: Date Format

Defines the format used to display the date in the BF_D tag variable. Use the characters y, m, and d as variables for the year, month, and day to show the desired format, along with any desired special characters as separators. For example, for the date September 21, 2005:

Format string....Output

ymd...050921

m/d/y...09/21/05

Tag: Time Format

Defines the format used to display the date in the BF_T tag variable. Works such as the Tag: Date format setting, but uses the characters h, m, and s to stand for hours, minutes, and seconds. The setting h:m:s produces output such as 12:53:42.

Tail Log Amount for Mail Template

Sets the number of lines from the end of a log that are displayed in a notification when the TAILNORMALLOG variable is used in the notification template.

Terminate Threads Determines whether, when a threaded step fails, all other active thread blocks in the same project are stopped.

Feedback