Settings

Many settings can be configured using the GUI by navigating to the 'person' menu at the top right of the Sal window and choosing settings. However, there are some settings that require editing a configuration file or adding settings to the database.

By modifying sal/settings.py you can customise how plugins and data is displayed in Sal. If you are upgrading from a previous version of Sal, refer to this document to see how your settings.py file should be changed to take advantage of any new features. There are defaults set in sal/system_settings.py, but they can be overridden if you choose.

The majority of settings are also exposed as environment variables for Docker. Add DOCKER_SAL_ to the beginning of the setting name (for example, -e DOCKER_SAL_ADD_TO_ALL_BUSINESS_UNITS="true")

Some settings are configured as rows in the SalSettings table in the database. See the section below for more information.

Basic Authentication on HTTP endpoints

Sal exposes several endpoints - some of these may contain confidential information (particularly any custom scripts from plugins). By default, the client scripts will use the client's key for basic http authentication. If for some reason you wish to disable this (if you cannot upgrade your client scripts, for example), you should set this to False. By default this is True, and it is strongly recommended you leave this enabled.

BASIC_AUTH = True

Automatically adding users to a Business Unit

In some situations, it may be desirable to automatically give all of your users access to all business units. To enable the feature, add the following to sal/settings.py:

ADD_TO_ALL_BUSINESS_UNITS = True

LIMIT_PLUGIN_TO_FRONT_PAGE

These plugins will only be shown on the front page. They will not appear anywhere else.

LIMIT_PLUGIN_TO_FRONT_PAGE = ['Uptime', 'Memory']

HIDE_PLUGIN_FROM_FRONT_PAGE

Once again, a list of plugin names. These will not be shown on the front page.

HIDE_PLUGIN_FROM_FRONT_PAGE = ['DiskSpace']

HIDE_PLUGIN_FROM_BUSINESS_UNIT

Specify which Business Unit IDs should be hidden from which plugins. The data should be a dictionary containing lists. The Business Unit ID will be shown in the URL when on that particular Business Unit's page.

HIDE_PLUGIN_FROM_BUSINESS_UNIT = {
    'Encryption':['1','2','4'],
    'DiskSpace':['5','7','9']
}

HIDE_PLUGIN_FROM_MACHINE_GROUP

Works exactly the same as HIDE_PLUGIN_FROM_BUSINESS_UNIT (although you are specifying the Machine Group ID, obviously!),

HIDE_PLUGIN_FROM_MACHINE_GROUP = {
    'DiskSpace':['1'],
    'Uptime':['2','8']
}

SEARCH_FACTS

As of Sal 3.2.8, you can add a list of Facter Facts to include in the basic search (the input box on every page). This is an exact match for the Fact name.

SEARCH_FACTS = ['company_info=>email']

SEARCH_CONDITIONS

As of Sal 3.2.8, you can add a list of Munki conditions to include in the basic search (the input box on every page). This is an exact match for the Condition name.

SEARCH_CONDITIONS = ['machine_type']

IGNORE_FACTS

These Facts will be discarded and will not be saved to the database. These are 'begins with' strings - this allows you to exclude whole structured Facts if you wish. For example, the following will exclude all of the child Facts (mountpoints=>/, mountpoints=>/dev, etc).

IGNORE_FACTS = ['munki_managed_installs=>', 'installed_packages=>', 'certificates=>', 'mountpoints=>']

If you are using Salt or Chef, you may want to ignore additional facts, just in case a user in your organization is using Puppet/Facter.

Salt

IGNORE_FACTS = ['counters=>', 'grain=>counters=>']

Chef

IGNORE_FACTS = ['counters=>', 'ohai=>counters=>']

EXCLUDED_FACTS

These Facts won't be displayed on the Machine Information page. This won't effect any plugins that rely on the Fact.

EXCLUDED_FACTS = {
    'sshrsakey',
    'sshfp_rsa',
    'sshfp_dsa',
    'sshdsakey',
}

EXCLUDED_CONDITIONS

The same as EXCLUDED_FACTS, but will hide Munki Conditions instead.

EXCLUDED_CONDITIONS = {
    'ipv4_address',
}

ADD_NEW_MACHINES

By default, machines that don't exist in Sal, but have a valid Machine Group Key will be created. If you are using Sal for inventory purposes (for example, signing Puppet Certificates), you may wish to disable this.

ADD_NEW_MACHINES = False

DEFAULT_MACHINE_GROUP_KEY

By default, all machine submissions must include a machine group key otherwise an error will occur. By defining this value to an existing machine group key then machines without a group key already defined in its preferences will be placed into this group. This can be used, for example, to determine which machines have not been setup properly with the correct machine group. You should not use this when you have basic HTTP auth enabled, as clients will be unable to communicate with Sal if they do not have a key explicitly set.

DEFAULT_MACHINE_GROUP_KEY = 'x1eru38unri08badpo0ux4ahz043hapbyqyixdz482l047u9xe60nn6cux1sj0ad5bq7hwblyzjpmaqb17psygfwlfeo4x6hozb1jejaf1nee6paj68glducdt5575dz'

HISTORICAL_FACTS

Normally only the most recent fact is recorded for a machine. Any facts defined here will also have historical data from each run kept in addition to the most recent run.

HISTORICAL_FACTS = [
    'memoryfree_mb',
]

ROOT_CA

This is a root CA that will be used to verify requests to other services (such as your Crypt server for the Crypt Status plugin

ROOT_CA = '/some/path/to/your/root.ca'

INACTIVE_UNDEPLOYED

This is the number of days that a machine hasn't checked in for when it is considered inactive (deployed=False). This means that it will no longer show up in widgets. This value must be an integer greater than 0.

# machines that haven't checked in for 180 days are 'undeployed'
INACTIVE_UNDEPLOYED = 180

DEPLOYED_ON_CHECKIN

If a machine is 'undeployed' and checks in again, setting this to true will mark the machine as deployed again.

DEPLOYED_ON_CHECKIN = False

Database Settings

Some settings use rows in the Sal database's SalSettings table to store their values. To easily access and edit these settings, login to Sal using an account with Global Admin privileges, and then click on the "person" menu in the upper righthand corner of the interface. Select the "Admin Site" menu item. Locate the "Server" section, and click on the "Sal settings" item to see the preconfigured settings. From here you can edit settings.

Restart after settings changes

Some settings are queried from the Sal database for every page view, but in places like the application inventory, where performance benefits from optimizations, the settings are queried once at module import. Therefore, to be on the safe side, after editing a setting below, restart Sal.

Automatic setting management

Please note: Certain settings are expected to exist and have default values. These settings, if deleted, will be re-added with default values. However, if the settings are set to different values than the defaults, they will of course be left alone.

inventory_exclusion_pattern

The Inventory feature of Sal allows you to specify a regular expression, via this setting, which will exclude application bundles which match from displaying in the web interface.

The regular expression dialect in use is the python standard library regex module's implementation.

filter_proxied_virtualization_apps

This setting determines whether to remove apps registered with macOS in the inventory from virtual machines hosted by Parallels or VMWare. These virtualization tools create proxied inventory entries for all apps in each of the extant VMs. For example, all apps in a Windows VM now show up in the Mac's inventory.

By default, Sal filters these out (default setting: true)

To disable this feature, use false or no.

datatable_page_length

Most of Sal's views which list things are displayed with a DataTable. This setting sets the initial number of records to display in any of these tables.

Please note: DataTables include a user-specified records dropdown which will override this setting.

crypt_url

Enter a complete URL to your Crypt server as the value for this setting, and the CryptStatus machine detail plugin will include a button that goes either to that machine's info page on Crypt, or Crypt's list view for non-escrowed machines.

ssh_account

As of version 3.0.1, Sal includes a machine detail widget named "Remote Connection", which allows users to initiate a VNC or SSH connection to the machine being displayed. The open handler for SSH URLs (at least Safari and Chrome) automatically makes the connection with the username of the console user. VNC connections will prompt for both username and password.

Setting ssh_account will add a username to all SSH and VNC URLs generated for machine detail pages for all users. The main use-case for this is organizations that use a generic account that is enabled for these remote connections.

Leave this setting unset to use the console username. The primary use-case for this scenario is organizations with machines bound to a directory service, and remote administration enabled for the connecting users or groups in which they have membership.

normalize_chromeos_versions

Introduced in 3.9.10. Will remove the device specific part of Chrome OS' version string. E.g 70.0.3538.7 becomes 70.0.3538.

show_inventory_install_counts

Getting the install count of an application for the inventory list view is costly, so it's possible to disable that column and simplify the database query by setting show_inventory_install_counts to false.