-
Notifications
You must be signed in to change notification settings - Fork 0
7.1 xoloserver config help
Chris Lasell edited this page Sep 27, 2025
·
1 revision
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
--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 "email: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:
email:[email protected]
--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 someone uses xadm to upload a .pkg, 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
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.
--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 told to use this
contact info to get approval.
This string could be an email address, a chat
channel, a phone number, etc.
Examples:
- '[email protected]'
- '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> Required if not already set
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.
TODO: Document the permissions needed by this
account.
TODO: Allow using api-clients
--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 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.
--jamf-auto-accept-xolo-eas For titles fully maintained 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.
--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 this value is 'api', and you are using Jamf Pro
11.6 or later, Xolo will use the Jamf API to upload
the package to your primary distribution point. API
uploads are only available in Jamf Pro 11.6 and
later, and will only upload to the primary
distribution point. Syncing to other distribution
points is not supported by the API.
If this value is a path, it is to an executable on
the xolo server 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 object
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 Xolo
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
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, e.g. various
cloud and file-server distribution points. While the
packages/upload endpoint of the Jamf Pro API
(v11.6+) will upload to the primary distribution
point, it won't upload to all the others you might
have.
--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.
-h, --help Show this message