-
Notifications
You must be signed in to change notification settings - Fork 0
7.1 xoloserver config help
Chris Lasell edited this page Apr 16, 2026
·
2 revisions
NAME
xoloserver config - Manage the server configuration file
SYNOPSIS
xoloserver config [--show] [--expand] [config_key ...]
xoloserver config --set --config-key=value ...
xoloserver config --help
DESCRIPTION
The Xolo server configuration file is a YAML file located at
/Library/Application Support/xoloserver/config.yaml"
It contains a Ruby Hash of configuration options, the keys are Symbols and the values are the
configuration values. While the file can be edited directly, it is recommended to use the
'config' subcommand to view and set the values.
Some sensitive values may be stored in the configuration file as a command or file path from
which to read the actual value. Config values starting with a pipe '|' are executed as a command
(after removing the pipe) and the value to be used is read from the standard output of the
command. Values that are file paths are read from the file at the path. If the stored value
doesn't start with a pipe, and is not a valid file path, the value is used as is. Be wary of
security issues, permissions, etc when working with these values.
See 'xoloserver config --help' for details on which configuration
keys are used this way.
Showing configuration values:
When used without --set, --show is implied. If no config keys are given, all keys are shown.
Keys can be given as 'key_name' or 'key-name'.
Values are shown as stored in the config file. With --expand, the actual value used by the server
is shown, after reading from commands or files.
Setting configuration values:
To set configuration values, use --set followed by one or more config keys as options, e.g.
--config-key=value. You must restart the server to apply changes.
NOTE: As of this writing, there is very little validation of the values you set, nor any
enforcement of required values. Be careful.
Help:
Using --help shows this help message, and descriptions of all available config_keys as options
to --set.
Private values:
Config keys marked Private (see xoloserver config --help) are
not shown when the config values are displayed to users of xadm, instead they see '<private>'
Options:
--show Show configuration values
--expand Show expanded configuration values
--set Set configuration values
--test-server Is this a development/testing server? If so, Objects
in Jamf will have the prefix 'xolotest-' rather than
just 'xolo-'
to avoid confusion and collision with production
objects, and some other things may be different as
well.
--ssl-cert=<s> Required if not already set [Private]
The SSL Certificate for the https server in .pem
format. When the server starts, it will be read from
here, and securely stored in /Library/Application
Support/xoloserver/ssl/cert.pem.
If you start this value with a vertical bar '|',
everything after the bar is a command to be executed
by the server at start-time.
The command must return the certificate to standard
output. This is useful when using a secret-storage
system to manage secrets.
If the value is a path to a readable file, the
file's contents are used.
Otherwise the value is used as the certificate.
Be careful of security concerns when certificates
are stored in files.
--ssl-key=<s> Required if not already set [Private]
The private key for the SSL Certificate in .pem
format. When the server starts, it will be read from
here, and securely stored in /Library/Application
Support/xoloserver/ssl/key.pem/
If you start this value with a vertical bar '|',
everything after the bar is a command to be executed
by the server at start-time.
The command must return the certificate to standard
output. This is useful when using a secret-storage
system to manage secrets.
If the value is a path to a readable file, the
file's contents are used.
Otherwise the value is used as the certificate.
Be careful of security concerns when certificates
are stored in files.
--ssl-verify, --no-ssl-verify Should the server verify the SSL certificates of
machines it communicates with, such as the Jamf Pro
server and the Title Editor server?
(default: true)
--admin-jamf-group=<s> Required if not already set
The name of a Jamf account-group (not a User group)
that allows the use of 'xadm' to create and maintain
titles and versions.
Users of xadm must be in this group, and provide
their valid Jamf credentials.
--server-admin-jamf-group=<s> The name of a Jamf account-group (not a User group)
that allows the use of the server admin commands of
'xadm', including --run-server-cleanup,
--update-client-data, --rotate-server-logs and
--set-server-log-level.
Members of this group can also use the xadm commands
that require the 'admin_jamf_group' group.
If unset, no one can use the server admin commands.
--log-days-to-keep=<i> The server log is rotated daily. How many days of
log files should be kept? All logs are kept in
/Library/Application Support/xoloserver/logs.
The current file is named 'xoloserver.log', older
files are appended with '.0' for yesterday, '.1' for
the previous day, etc.
(default: 30)
--log-compress-after-days=<i> Once a log file is rotated, how many days before it
is compressed? Compressed logs are named
'xoloserver.log.XX.bz2'.
It can be accessed using the various bzip2 tools
(bzip2, bunzip2, bzcat, bzgrep, etc). If this number
is negative, or larger than log_days_to_keep,
no logs will be compressed, if it is zero, all older
logs will be compressed.
(default: 7)
--alert-tool=<s> Server errors or other events that happen as part of
xadm actions are reported to the xadm user. But
sometimes such events happen outside of the scope
of a xadm session. While these events will be
logged, you might want them reported to a server
administrator in real time.
This value is either:
- a command (path to executable plus CLI args) on
the Xolo server which will accept an error or other
alert message on standard input and send it
somewhere where it'll be seen by an appropriate
audiance, be that an email address, a Slack channel
- anything you'd like.
- or a string "mailto:email_address" where
email_address is the email address to send alerts
to.
In this case, the server will send an email to that
address using the smtp_server and email_from
configuration values.
Fictional command example:
/path/to/slackerator --sender xolo-server
--channel xolo-alerts --icon dante
Fictional email example:
mailto:xolo-server-admins@myschool.edu
While not required, it is strongly recommended to
use this, so that server admins are made aware of
issues that need their attention.
--pkg-signing-identity=<s> Required if not already set
Xolo needs to be able to sign at least one of the
packages it maintains: the client-data pkg which
installs a JSON file of title and version data on
the client machines.
To sign that, or oher packages, you must install a
keychain containing a valid package-signing identity
on the xolo server at:
/Library/Application
Support/xoloserver/xolo-pkg-signing.keychain-db
The 'identity' (name) of the package-signing
certificate inside the keychain must be set here. It
usually looks something like:
Developer ID Installer: My Company (XYZXYZYXZXYZ)
If desired, you can use this identity to sign other
packages as well, see the 'sign_pkgs' config value.
--pkg-signing-keychain-pw=<s> Required if not already set [Private]
The password to unlock the keychain used for package
signing.
If you start this value with a vertical bar '|',
everything after the bar is a command to be executed
by the server at start-time.
The command must return the certificate to standard
output. This is useful when using a secret-storage
system to manage secrets.
If the value is a path to a readable file, the
file's contents are used.
Otherwise the value is used as the password.
Be careful of security concerns when passwords are
stored in files.
--sign-pkgs When a .pkg, is received for a version and it isn't
signed, should the server sign it before uploading
to Jamf's Distribution Point(s)?
If you set this to true, it will use the same
keychain and identity as the 'pkg_signing_identity'
config value to sign the pkg, using the keychain you
installed at:
/Library/Application
Support/xoloserver/xolo-pkg-signing.keychain-db
Packages must be signed distribution packages to
work with the `xadm deploy` command, which uses MDM
to push the package to client machines.
NOTE: While it may seem insecure to allow the server
to sign pkgs, consider:
- Users of xadm are authenticated and authorized to
use the server (see 'admin_jamf_group')
- You don't need to distribute your signing
certificates to a wide group of individual
developers.
- While you need to trust your xadm users not to
upload a malicious pkg, this would be true
even if you deployed the certs to them, so keeping
the certs on the server is more secure.
See also the 'sign_autopkg_pkgs' abd
'create_distribution_pkgs' config values.
--create-distribution-pkgs When a .pkg, is received for a version and it is a
component package, should the server wrap it in a
distribution package before uploading to Jamf's
Distribution Point(s)?
If you set this to true, component packages will be
wrapped in a distribution package using the
productbuild tool, like so:
/usr/bin/productbuild –package
/path/to/recieved.pkg
/path/to/distribution_package.pkg
If sign_pkgs is true, the distribution package will
be signed, otherwise it will be unsigned.
Packages must be signed distribution packages to
work with the `xadm deploy` command, which uses MDM
to push the package to client machines.
--release-to-all-jamf-group=<s> The name of a Jamf account-group (not a User group)
whose members may set a title's release_groups to
'all'.
When this is set, and someone not in this group
tries to set a title's release_groups to 'all', they
will get a message telling
them to contact the person or group named in
'release_to_all_contact' to get approval.
To approve the request, one of the members of this
group must run 'xadm edit-title <title>
--release-groups all'.
Leave this unset to allow anyone using xadm to set
release_groups to 'all' without approval.
--release-to-all-contact=<s> When release_to_all_jamf_group is set, and someone
not in that group tries to set a title's
release_groups to 'all', they are
old to use this contact info to get approval.
This string could be an email address, a chat
channel, a phone number, etc.
Examples:
- 'jamf-admins@myschool.edu'
- 'the IT deployment team in the #deployment
channel on Slack'
- 'Bob Parr at 555-555-5555'
It is presented in text along the lines of:
Please contact <value> to set release_groups to
'all', letting us know why you think the title
should be automatically deployed to all computers.
This value is required if release_to_all_jamf_group
is set.
--default-min-os=<s> The default minimum OS version for new versions of
titles. This is used when a new version is created,
and no minimum OS is specified.
In Jamf Packages, this will appear in the OS
limitations expanded to macOS 40, or max_os if
specified for the version.
If not specified here, the default is 10.9.
--deprecated-lifetime-days=<i> When a version is deprecated, it will be
automatically deleted by the nightly cleanup this
many days later. If set to 0 or less,
deprecated versions will never be deleted.
Deprecated versions are those that have been
released, but a newer version has been released
since then.
WARNING: If you set this to 0 or less, you will need
to manually delete deprecated versions. Keeping them
around can cause confusion
and clutter in the GUI, and use up disk space.
(default: 30)
--keep-skipped-versions Normally, skipped versions are deleted during
nightly cleanup. If you set this to true, skipped
versions will be kept.
Skipped versions are those that were never released,
but a newer version has been released.
WARNING: If you set this to true, you will need to
manually delete skipped versions. Keeping them
around can cause confusion
and clutter in the GUI, and use up disk space.
--unreleased-pilots-notification-days=<i> If the newest pilot of a title has not been released
in this many days, notify someone about it monthly,
asking to release it or delete it.
If set to 0 or less, these notifications are
disabled.
Notifications are sent on the first of the month via
email to the title's contact email address, and the
alert_tool (if defined).
Default is 180 days (about 6 months).
Pilot versions are those that have been added for
testing, but not yet released.
This is useful to keep the Xolo server clean and
up-to-date, and to avoid cluttering with unreleased
versions or titles that are no longer relevant.
(default: 180)
--smtp-server=<s> The hostname of the SMTP server to use for sending
email. This is a server that can recieve email for
your organizaion from the xolo server.
Used for sending alerts and notifications. If not
set, no email notifications will be sent.
--email-from=<s> The email address to use as the 'from' address for
emails sent by xolo. This should be a valid email
address that can recieve replies.
Will default to
'xolo-server-do-not-reply@<hostname>' if not set.
The human-readable part of the address
will be 'Xolo Server on <hostname>'.
--jamf-hostname=<s> Required if not already set
The hostname of the Jamf Pro server used by xolo for
API access.
--jamf-port=<i> The port number of the Jamf Pro server used by xolo
for API access.
The default is 443 if the Jamf Pro hostname ends
with jamfcloud.com and 8443 otherwise.
(default: 443)
--jamf-gui-hostname=<s> The hostname of the Jamf Pro server used for links
to the GUI webapp, if different from the
jamf_hostname.
--jamf-gui-port=<i> The port number of the Jamf Pro server used for
links to the GUI webapp, if different from the
jamf_port.
The default is 443 if the Jamf Pro hostname ends
with jamfcloud.com and 8443 otherwise.
(default: 443)
--jamf-ssl-version=<s> The SSL version to use for the connection to the
Jamf API.
(default: TLSv1_2)
--jamf-verify-cert, --no-jamf-verify-cert Should we verify the SSL certificate used by the
Jamf Pro server?
(default: true)
--jamf-open-timeout=<i> The timeout, in seconds, for establishing a
connection to the Jamf Pro server.
The default is 60.
(default: 60)
--jamf-timeout=<i> The timeout, in seconds, for getting a response to a
request made to the Jamf Pro server.
The default is 60.
(default: 60)
--jamf-api-user=<s> Required if not already set
The username of the Jamf account for connecting to
the Jamf Pro APIs.
If you start this value with a vertical bar '|',
everything after the bar is a shell command to be
executed by the server at start-time.
The command must return the password to standard
output. This is useful when using a secret-storage
system to manage secrets.
If the value is a path to a readable file, the
file's contents are used.
Otherwise the value is used as the password.
--jamf-api-pw=<s> Required if not already set [Private]
The password for the username that connects to the
Jamf Pro APIs.
If you start this value with a vertical bar '|',
everything after the bar is a shell command to be
executed by the server at start-time.
The command must return the password to standard
output. This is useful when using a secret-storage
system to manage secrets.
If the value is a path to a readable file, the
file's contents are used.
Otherwise the value is used as the password.
Be careful of security concerns when passwords are
stored in files.
--jamf-use-api-client If true, the provided jamf_api_user is an API
client's "client_id", not a normal username, and the
jamf_api_pw is the API client's 'client_secret'.
If false, the jamf_api_user is a normal user, and
the jamf_api_pw is that user's password.
--jamf-auto-accept-xolo-eas For titles managed by Xolo, should we auto-accept
the Patch Title Extension Attributes that come from
the uploaded version_script from xadm?
Default is false, meaning all Title EAs must be
manually accepted in the Jamf Pro Web UI.
EAs must always be manually accepted for subscribed
titles, since the code the run is not under the
control of Xolo.
--upload-tool=<s> Required if not already set
After a .pkg is uploaded to the Xolo server by
someone using xadm, it must then be uploaded to the
Jamf distribution point(s) to be available for
installation.
If your principal distribution point is a Cloud
Distribution Point and you're using Jamf Pro 11.6 or
later, you can set this value to 'api', and
xoloserver will use the Jamf Pro API to upload the
pkg to the Cloud Distribution Point. This is the
simplest option, and is recommended if it works for
your environment.
If your principal is not a Cloud Distribution Point,
xoloserver can use an custom external tool to do the
upload.
To do so, set this value to a path to an executable
on the xolo server machine that will do the upload
to the distribution point(s). This tool can be
anything you like, as long as it can upload a .pkg
to the Jamf distribution point(s) you use.
It will be run with two arguments:
- First, The display name of the Jamf Package record
the .pkg is used with
- Then the path to the .pkg file on the Xolo server,
which will be uploaded
to the Jamf distribution point(s).
So if the executable is
'/usr/local/bin/jamf-pkg-uploader' then when
xoloserver recieves a .pkg to be uploaded to Jamf,
it will run something like:
/usr/local/bin/jamf-pkg-uploader 'CoolApp'
'/Library/Application
Support/xoloserver/tmpfiles/CoolApp.pkg'
Where 'CoolApp' is the name of the Jamf Package
object that will use this .pkg, and
'/Library/Application
Support/xoloserver/tmpfiles/CoolApp.pkg' is the
location where it was stored on the Xolo server when
xadm uploaded it.
The upload tool can itself run other tools as
needed, e.g. one to upload to all fileshare
distribution points, and another to upload to a
Cloud dist. point, or it can do all the things
itself.
After that tool runs, the copy of the .pkg on the
xolo server ('/Library/Application
Support/xoloserver/tmpfiles/CoolApp.pkg' in the
example above) will be deleted.
An external tool is used here because every Jamf Pro
customer has different needs for this depending on
their environment of distribution points.
--forced-exclusion=<s> If you have any jamf computers who should never even
know that xolo exists, and should never have any
software installed via xolo, put them
into a group and put that group's name here.
An example would be a group of machines that should
have a very minimalist management footprint, only
enforcing basic security settings and nothing else.
This group, if defined, will be in the exclusions of
all policies and patch policies maintained by Xolo.
NOTE: These machines are still managed, and software
can still be installed via Jamf if desired, but
outside of Xolo.
--ted-patch-source=<s> Required if not already set
The name in Jamf Pro of the Title Editor as an
External Patch Source.
--ted-hostname=<s> Required if not already set
The hostname of the Title Editor server used by
xolo.
--ted-open-timeout=<i> The timeout, in seconds, for establishing a
connection to the Title Editor server.
(default: 60)
--ted-timeout=<i> The timeout, in seconds, for getting a response to a
request made to the Title Editor server.
(default: 60)
--ted-api-user=<s> Required if not already set
The username of the Title Editor account for
connecting to the Title Editor API.
TODO: Document the permissions needed by this
account.
--ted-api-pw=<s> Required if not already set [Private]
The password for the username that connects to the
Title Editor API.
If you start this value with a vertical bar '|',
everything after the bar is a command to be executed
by the server at start-time.
The command must return the certificate to standard
output. This is useful when using a secret-storage
system to manage secrets.
If the value is a path to a readable file, the
file's contents are used.
Otherwise the value is used as the password.
Be careful of security concerns when passwords are
stored in files.
--subscription-webhook-token=<s> [Private]
The authentication token used by Jamf Pro to send
PatchSoftwareTitleUpdated webhook events for
subscribed titles.
This value can be string, but should be treated like
a password, and should be changed both here and on
the Jamf Pro server if it is ever suspected of being
compromised.
A good way to generate a random token is to use the
following command in Terminal:
openssl rand -hex 16
When configuring the webhook in Jamf Pro, use
"Header Authentication" to send this JSON to use as
the header:
{"Authorization":"Bearer <token>"}
Replacing <token> with the value set here.
If you start this value with a vertical bar '|',
everything after the bar is a command to be executed
by the server at start-time.
The command must return the password to standard
output. This is useful when using a secret-storage
system to manage secrets.
If the value is a path to a readable file, the
file's contents are used.
Otherwise the value is used as the token.
Be careful of security concerns when secrets are
stored in files.
--subscription-updated-alert-tool=<s> If a title is a subscription from a Patch Source,
but is not configured to use autopkg to fetch new
versions, when a PatchSoftwareTitleUpdated webhook
event is received from Jamf Pro, an alert should be
sent to notify someone to add the new version
manually.
Leave this unset to use the default alert mechanism
defined by the 'alert_tool' configuration value.
Otherwise, the value is interpreted the same as for
'alert_tool', either a command to run, or an email
address prefixed by "mailto:".
--autopkg-executable=<s> The path to the autopkg executable on the server
host. If unset, titles cannot use autopkg to acquire
new .pkgs.
AutoPkg must be installed, configured, and
maintained on the xoloserver host separately from
the xoloserver itself.
NOTE: AutoPkg recipes are always run with '-k
FAIL_RECIPES_WITHOUT_TRUST_INFO=yes', and will fail
if you have not 'trusted'
them by making an override. See the AutoPkg docs for
details.
--autopkg-user=<s> The name of a local, non-root user that will run the
autopkg executable as needed. AutoPkg should never
be run as root.
If unset, titles cannot use autopkg to acquire new
.pkgs.
AutoPkg must be installed, configured, and
maintained on the xoloserver host separately from
the xoloserver itself.
NOTE: AutoPkg recipes are always run with '-k
FAIL_RECIPES_WITHOUT_TRUST_INFO=yes', and will fail
if you have not 'trusted'
them by making an override. See the AutoPkg docs for
details.
--autopkg-user-keychain-pw=<s> Required if not already set [Private]
The password for the login keychain of the
autopkg_user.
Some autopkg recipes may attempt to sign apps or
packages, which requires access to the
autopkg_user's login keychain.
Since the user is not expected to be logged into the
macOS GUI on the server (and even if it were, the
xoloserver process doesn't have
access to the GUI context) the keychain will be
locked, and must be unlocked by the server before
running autopkg recipes that need it.
This config value is used to unlock that keychain
when running autopkg recipes. The keychain used is
the one located at
/Users/<autopkg_user>/Library/Keychains/login.keychain-db. Be sure the desired signing identities are in that keychain, and that the
keychain is set to allow various executables to
access them without prompting, including the autopkg
itself, codesign, productsign,
pkgbuild, and productbuild.
If you start this value with a vertical bar '|',
everything after the bar is a command to be executed
by the server at start-time.
The command must return the password to standard
output. This is useful when using a secret-storage
system to manage secrets.
If the value is a path to a readable file, the
file's contents are used.
Otherwise the value is used as the password.
Be careful of security concerns when passwords are
stored in files.
--sign-autopkg-pkgs This is just like sign_pkgs, but only applies to
pkgs acquired via autopkg.
Be sure you trust your autopkg recipes to only
download safe pkgs if you enable this.
Packages must be signed distribution packages to
work with the `xadm deploy` command, which uses MDM
to push the package to client machines.
NOTE: AutoPkg recipes are always run with '-k
FAIL_RECIPES_WITHOUT_TRUST_INFO=yes', and will fail
if you have not 'trusted'
them by making an override. See the AutoPkg docs for
details.
-h, --help Show this message