Configuration file options

  • Release version: Yokohama
  • Updated March 12, 2026
  • 4 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Configuration File Options for acc.yml (Yokohama Release)

    Theacc.ymlconfiguration file enables ServiceNow customers to control the settings of the Agent Client Collector (ACC) for optimized connectivity, security, logging, and operational behavior. These configurations govern how the ACC interacts with MID Servers, handles authentication, manages plugins, and processes network communication. Proper configuration ensures secure, reliable, and efficient agent operations within your ServiceNow environment.

    Show full answer Show less

    Basic Configuration Options

    • Agent Identification: The name parameter sets the agent name, defaulting to the host’s hostname, allowing clear registration on the ServiceNow instance.
    • MID Server Communication: backend-url lists MID Webserver endpoints for resilient connections, used primarily when enable-auto-mid-selection is enabled.
    • Authentication: Parameters api-key, user, and password authenticate the agent to the MID Server using secure, encrypted credentials; these are mandatory for agent startup.
    • Logging Control: The log-level defines the verbosity of the ACC log file, supporting levels from Panic to Debug for troubleshooting and monitoring needs.
    • Security via Allow List: The allow-list designates a JSON file specifying permitted check commands, enhancing security by restricting agent actions. This can be disabled if necessary.
    • Application Classification: The applclassificationbehavior setting controls whether shell Configuration Items (CIs) are created on the agent, ranging from off to full discovery modes.

    Advanced Configuration Options

    • Plugin Security: verify-plugin-signature enables validation of plugin signatures to ensure integrity, which can be disabled for development or self-signed plugins.
    • TLS Verification: The insecure-skip-tls-verify flag lets you control whether TLS certificates are fully verified, enhancing security when set to false.
    • Auto MID Server Selection: enable-auto-mid-selection allows the agent to automatically connect to the optimal MID Server endpoint.
    • Command Execution Preference: check-command-prefer-installed specifies whether to prefer host system executables over ACC plugin executables.
    • Log Redaction: command-log-redaction-regex defines a regex pattern to mask sensitive information in logs and payloads, protecting credentials and user data.
    • PowerShell Execution: The powershellinstalled parameter enables or disables PowerShell command execution on agents.
    • Allow List Scope: allow-list-global-only restricts allowed commands strictly to those defined in the specified allow list, ignoring bundled plugin allow lists for enhanced security.
    • Asset Plugin Management: disable-assets controls whether ACC plugins can be downloaded during execution, supporting air-gapped or restricted environments.
    • Agent Upgrade Source: agent-upgrade-url-path defines a custom URL for downloading ACC installer packages during upgrades.
    • Certificate Rotation: certificate-rotation-days-out sets how many days before expiration the agent attempts certificate rotation, maintaining secure communications.
    • Pattern Execution: enable-patterns-on-agent enables detailed application pattern discovery on the agent when using ACC for pattern execution.
    • Keepalive Network Settings: Parameters keepalive-filter-nics and keepalive-numbernicsperiptype control which network interfaces and how many per IP type are reported during keepalive actions.

    Proxy Auto-Configuration (PAC) Parameters

    • PAC File Location: The mandatory pac-file points to a local or remote PAC file to configure proxy settings for the agent.
    • Caching and Refresh: pac-cache-ttl defines how long proxy rules are cached, and pac-refresh-interval controls how often the agent checks for updates to the PAC file, ensuring up-to-date proxy configurations.
    • Connection Timeout: pac-dial-timeout sets the timeout duration when establishing proxy connections.
    • Error Recovery: pac-reset-on-connect-failure enables the agent to clear the PAC cache and refresh the PAC file upon proxy connection failures, improving resilience.

    Practical Benefits

    Configuring the acc.yml file with these options empowers ServiceNow customers to:

    • Ensure secure, authenticated communication between ACC agents and MID Servers.
      • <

    Options available in the acc.yml configuration file.

    Table 1. Basic configuration options for acc.yml configuration file
    Option Type Default Description Example
    name String Agent_<value of the hostname command> Agent name registered on the SN instance can be specified by the user. The result of the 'hostname' command is used as the default. name: <name of agent>
    backend-url List wss://127.0.0.1:8800/ws/events List of MID Webserver endpoint URLs to communicate with. If communication cannot be configured with the first URL, the system moves to the ensuing URLs until it establishes a connection. Works when enable-auto-mid-selection=true backend-url: <mid server ip>:<websocket port>
    api-key String <None> API key used by the MID Server to authenticate incoming agent connections. Value is encrypted on initial agent startup. api-key: <mid web server api key>
    user String admin Username used for basic authentication.

    If this parameter is empty, the agent does not start.

    		 user: "agent-01"
    password String admin Password used for basic authentication. Value is encrypted on initial agent startup.

    If this parameter is empty, the agent does not start.

    		 password: <secure-password>
    log-level String Info Amount of logging to appear in the acc.log file. Values:
    • Panic
    • Fatal
    • Error
    • Warn
    • Info
    • Debug
    		 log-level: debug
    allow-list String /etc/servicenow/agent-client-collector/check-allow-list.json Path to the JSON file that contains the list of check commands the agent can execute. Comment out this parameter to disable the allow-list.

    If this parameter is empty, the allow-list is disabled.

    		 allow-list: /etc/agent/check-allow-list.json
    appl_classification_behavior List simple Indicates whether to enable shell CI creation on the agent.
    Possible values are:
    • simple: Indicates that shell CI creation is enabled.
    • off: Indicates that no shell CIs are created for the application.
    • full: Indicates that complete Discovery of the application CIs is performed using patterns.
    		 appl_classification_behavior: off
    Table 2. Advanced configuration options for acc.yml configuration file
    Option Type Default Description Example
    verify-plugin-signature Boolean true Verifies the plugin signature before execution. Disable when using self-signed or developmental plugins. verify-plugin-signature: true
    insecure-skip-tls-verify Boolean true Determines whether to verify the certificate when connecting to the MID Server.

    Set as false to enforce full TLS verification.

    		 insecure-skip-tls-verify: true
    enable-auto-mid-selection Boolean true Controls the Auto MID Selection feature to connect to the optimal MID Web Server provided by the instance. enable-auto-mid-selection: true
    check-command-prefer-installed Boolean false Indicates the preference of executables provided within ACC plugins or executables available in the host system’s PATH variable.
    • false = ACC plugins
    • true = Executables in the host system's PATH variable
    		 check-command-prefer-installed: false
    command-log-redaction-regex String '-password[=\s]([^"\s]+)|-[pP]\s([^"\s]+)|--user\s[^":\s]+:([^\s"]+)|-pw\s([^"\s]+)|-u\s[^":\s]+:([^\s"]+)|[^"\s]+/([^\s"]+)@‘ The regex to search for and to remove potentially sensitive user information from ACC logs and payloads. '-password[=\s]([^"\s]+)|-[pP]\s([^"\s]+)|--user\s[^":\s]+:([^\s"]+)|-pw\s([^"\s]+)|-u\s[^":\s]+:([^\s"]+)|[^"\s]+/([^\s"]+)@‘
    powershell_installed Boolean false Disables powershell command execution on agents. powershell_installed: true
    allow-list-global-only Boolean false Set to true to enhance security by relying only on the allow list defined in the allow-list parameter you specify during configuration, ignoring allow lists bundled with ACC plugins. allow-list-global-only: false
    disable-assets Boolean false Indicates whether a check running with an asset (plugin) dependency fetches ACC plugins from the ServiceNow® instance, or uses a copy of the plugins in its cache folder.

    When set to false, additional assets can be downloaded during check execution.

    Set to true to enhance security and ensure that no new plugins are downloaded during check execution.

    		 disable-assets: false
    agent-upgrade-url-path String https://install.service-now.com/glide/distribution/builds/package/app-signed/ Indicates an alternate web server URL endpoint for downloading ACC installer packages when performing selective upgrade. agent-upgrade-url-path: https://<ip address>:<port>/acc_installers
    certificate-rotation-days-out Integer 28 Indicates the number of days before certificate expiration that an agent attempts to rotate its certificate. certificate-rotation-days-out=28
    enable-patterns-on-agent Boolean false Enables gathering details on the applications which run on the Agent Client Collector.

    This parameter is required only when using the Agent Client Collector for pattern execution.

    		 enable-patterns-on-agent: true
    keepalive-filter-nics Boolean true Indicates whether Network Interface Controllers (NICs) are filtered on the agent (true) or the MID Server (false) during keepalive action. keepalive-filter-nics: true
    keepalive-number_nics_per_ip_type Integer 1 Indicates the maximum number of Network Interface Controllers (NICs) per IP type (IP4, IP6) sent with a keepalive action. The indicated number is sent for each IP type.

    For example, if the value is 1, a maximum of 2 NICs are sent (0-1 each for IP4 and IP6). If the value is 4, a maximum of 8 NICs are sent (0-4 each for IP4 and IP6).

    		 keepalive-number_nics_per_ip_type: 4
    Table 3. Proxy Auto-Configuration (PAC) file parameters
    Option Type Default Description Example
    pac-file String

    (Required)

    		 "" (empty) Specifies the location of the PAC file to use for proxy configuration. Can be either:
    • A local file path (such as: file:///etc/proxy/proxy.pac)
    • A remote URL (such as: https://proxy.company.com/proxy.pac)
    		 pac-file: "https://proxy.company.com/proxy.pac"
    pac-cache-ttl Duration

    (Optional)

    		 30m (30 minutes) Determines how long proxy rules from the PAC file are cached in memory.

    Setting this to 0 disables caching.

    		 pac-cache-ttl: "1h" # Cache for 1 hour
    pac-refresh-interval Duration

    (Optional)

    		 30m (30 minutes) Specifies how often the agent is to check for updates to the PAC file.

    Useful when the PAC file is hosted remotely and may be updated periodically.

    		 pac-refresh-interval: "15m" # Check for updates every 15 minutes
    pac-dial-timeout Duration

    (Optional)

    		 30s (30 seconds) Indicates the amount of time to wait when establishing a connection through a proxy server before timing out. pac-dial-timeout: "10s" # 10 second timeout
    pac-reset-on-connect-failure Boolean

    (Optional)

    		 true When set to true, the agent clears the PAC cache and attempts to refresh the PAC file if a proxy connection proxy fails. This helps recover from proxy configuration changes or temporary proxy issues. pac-reset-on-connect-failure: true