This section describes how to customize the rules restricting agents' access to the Jenkins controller in Jenkins 2.325 and earlier.
|In Jenkins 2.326, the ability to disable or customize the agent-to-controller security system has been removed without replacement. This documentation applies only to older releases of Jenkins. For documentation specific to the change in Jenkins 2.326, see Agent → Controller Security Changes in 2.326.|
Sophisticated administrators can use the built-in access control rules to create specific exemptions for certain access patterns from the agents to the Jenkins controller. This should only be necessary when trying to run plugins that have not yet been adapted to be compatible.
|For an introduction about the Agent → Controller Security system, see Isolating the Controller from Builds.|
By following the link highlighted above, an administrator may edit Commands and File Access agent-to-controller access control rules.
"Commands" in Jenkins and its plugins are identified by their fully-qualified class names. The majority of these commands are intended to be executed on agents by a request of a controller, but some of them are intended to be executed on a controller by a request of an agent.
Plugins not yet updated for this subsystem may not classify which category each command falls into, such that when an agent requests that the controller execute a command which is not explicitly allowed, Jenkins will err on the side of caution and refuse to execute the command.
In such cases, Jenkins administrators may allow certain commands as acceptable for execution on the controller.
Administrators may also allow classes by creating files with the
.conf extension in the directory
The contents of these
.conf files should list command names on separate lines.
The contents of all the
.conf files in the directory will be read by Jenkins and combined to create a
default.conf file in the directory which lists all known safe commands.
default.conf file will be re-written each time Jenkins boots.
Jenkins also manages a file named
gui.conf, in the
whitelisted-callables.d directory, where commands added via the web UI are written.
In order to disable the ability of administrators to change whitelisted commands from the web UI, place an empty
gui.conf file in the directory and change its permissions such that is not writeable by the operating system user Jenkins run as.
The File Access Rules are used to validate file access requests made from agents to the controller. Each File Access Rule is a triplet which must contain each of the following elements:
deny: if the following two parameters match the current request being considered, an
allow entry would allow the request to be carried out and a
deny entry would deny the request to be rejected, regardless of what later rules might say.
operation: Type of the operation requested.
The following 6 values exist.
The operations can also be combined by comma-separating the values.
The value of
all indicates all the listed operations are allowed or denied.
read: read file content or list directory entries
write: write file content
mkdirs: create a new directory
create: create a file in an existing directory
delete: delete a file or directory
stat: read metadata of a file/directory, such as timestamp, length, file access modes.
file path: regular expression that specifies file paths that matches this rule. In addition to the base regexp syntax, it supports the following tokens:
<JENKINS_HOME> can be used as a prefix to match the controller’s
<BUILDDIR> can be used as a prefix to match the build record directory, such as
<BUILDID> matches the timestamp-formatted build IDs, like
The rules are ordered, and applied in that order.
The earliest match wins.
For example, the following rules allow access to all files in
JENKINS_HOME except the
# To avoid hassle of escaping every '\' on Windows, you can use / even on Windows. deny all <JENKINS_HOME>/secrets/.* allow all <JENKINS_HOME>/.*
Ordering is very important! The following rules are incorrectly written because the second rule will never match, and allow all agents to access all files and folders under
allow all <JENKINS_HOME>/.* deny all <JENKINS_HOME>/secrets/.*
Administrators may also add File Access Rules by creating files with the
.conf. extension in the directory
Jenkins itself generates the
30-default.conf file on boot in this directory which contains defaults considered the best balance between compatibility and security by the Jenkins project.
In order to disable these built-in defaults, replace
30-default.conf with an empty file which is not writable by the operating system user Jenkins run as.
On each startup, Jenkins will read all
.conf files in the
filepath-filters.d directory in alphabetical order, therefore it is good practice to name files in a manner which indicates their load order.
Jenkins also manages
50-gui.conf, in the
filepath-filters/ directory, where File Access Rules added via the web UI are written.
In order to disable the ability of administrators to change the File Access Rules from the web UI, place an empty
50-gui.conf file in the directory and change its permissions such that is not writeable by the operating system user Jenkins run as.
While it is not recommended, if all agents in a Jenkins environment can be considered "trusted" to the same degree that the controller is trusted, the Agent/Master Access Control feature may be disabled.
Additionally, all the users in the Jenkins environment should have the same level of access to all configured projects.
An administrator can disable Agent to Controller Access Control in the web UI by un-checking the box on the Configure Global Security page.
Alternatively an administrator may create a file in
slave-to-master-security-kill-switch with the contents of
true and restart Jenkins.
Most Jenkins environments grow over time requiring their trust models to evolve as the environment grows. Please consider scheduling regular "check-ups" to review whether any disabled security settings should be re-enabled.