Configuring the CLI

You can configure default database settings by executing the following command followed by at least one of the database configuration flags listed below:
jamf-pro config set

Configuration Flags

Following is a list of configuration flags that you can add to the base jamf-pro config set command to define various settings:
--database-host
--database-port
--database-name
--database-user
--database-password
--backup-dir
--backup-limit
--tomcat-dir
--tomcat-service
--mysql-service
--mysql-home
Note:

It is recommended that you execute the jamf-pro config list command after executing any jamf-pro config command to ensure the configuration values you intended were saved.

Verbose Output

You can add the following flags to any command to generate verbose output:
-v
or
--verbose

Using sudo on Linux and Mac

It is recommended to not use sudo with the jamf-pro config command, i.e., sudo jamf-pro config. However, if you need to use sudo in your environment, be aware of the following:
  • The sudo command may not use the expected home directory. You may need to use the su command or the sudo su command to reach the root user account to set configuration options for jamf-pro.

    • If you use the su command, you must provide the root user password.

    • If you use the sudo su command, you can access the root user account by providing the password of the current account. Note that the current account must be configured in the sudoers file to use sudo su.

  • Some CLI commands may require sudo. If you receive an error similar to jamf-pro: command not found, the sudo path may not be configured properly. To resolve this issue, run sudo using the full path to the jamf-pro binary. For example:
    sudo /usr/local/bin/jamf-pro server restart

Configuration File Permissions

On Linux and Mac, the permissions for the configuration file (located at $HOME/.jamf/tools.yaml) are read/write for only the file owner (i.e., rw-------, or mode 600).

Configuration File Locations

Linux and Mac
On Linux and Mac, the configuration file is stored in the following locations:
  • User-based location (default): $HOME/.jamf/tools.yaml

  • Global location (optional): /etc/jamf/tools.yaml

Windows
On Windows, the configuration file is stored in the following locations:
  • User-based location (default): %LOCALAPPDATA%\Jamf\tools.yaml

    A typical path is: C:\Users\<username>\AppData\Local\Jamf\tools.yaml

  • Global location (optional): %ProgramData%\Jamf\tools.yaml

    A typical path is: C:\ProgramData\Jamf\tools.yaml

Global Location
You can use the global location to make the CLI configurations available to all users. To use the global location, you must manually move the tools.yaml file to the global location listed for your platform above.
Warning:
The tools.yaml file is not encrypted by default. Moving the tools.yaml file to a global location will make it accessible to all user accounts. If you move the tools.yaml file to a global location, it is recommended that you enable encryption by executing the following command:
jamf-pro config encrypt set-password
For more information, see "Full Encryption" below.

Security Commands

This section lists common security commands that you can use to customize the encryption settings for the CLI.

List all security commands
jamf-pro config encrypt --help
Encrypt changes or set a configuration file encryption key
jamf-pro config encrypt [command]
Reset configuration password (removes encrypted settings)
jamf-pro config encrypt forgot-password
Remove configuration password and use password-less configuration
jamf-pro config encrypt remove-password
Note:

Resetting or removing the password will require you to reset any configured password with the CLI.

Create or update a password to encrypt the configuration file
jamf-pro config encrypt set-password

Security Mechanisms

Default Security
The default security mechanism allows commands to be run without prompting for settings or passwords. Database connection settings remain secure and can be used in scripted or automated scenarios like scheduled backups.
By default, two layers of security are used to secure configuration settings:
  • The configuration file permissions must be read/write for only the current user. If insecure permissions are detected, commands will not execute and an error will be displayed.

  • All database fields in the configuration file are encrypted using a default key. This is the same level of security MySQL uses for protecting its login configuration settings.

    Warning:

    Configuration settings saved using the default encryption key are not encrypted; they are merely obfuscated. Obfuscation can deter attackers because it makes the settings difficult to read, however, the obfuscated settings provide no greater protection than if the settings were saved as plain text. For this reason, you should make sure the file permissions on the configuration file are always secured.

Full Encryption
For additional security, you can enable full encryption of the configuration file. This feature allows the configuration file to be fully encrypted using a custom encryption key (i.e., password) known only to you. You will then be prompted to enter that key anytime the configuration file needs to be read or updated, such as displaying the configuration with jamf-pro config list or backing up and restoring the database.
Note:

Using full encryption requires you to enter your encryption key for each command. Automatic scheduled backups are not possible if full encryption is enabled.

To enable full encryption, execute the following command, and create an encryption key password when prompted:
jamf-pro config encrypt set-password
Note:

Using this option, data at rest is fully encrypted using AES 256 encryption and a PBKDF2 key generated from the password.

For example, you can set the database password by executing the following command:
jamf-pro config set --database-password p@$$w0rd