Skip to content

Installing xoloserver

Jump to bottom
Chris Lasell edited this page Mar 17, 2026 · 6 revisions

Setting up a Xolo Server

These instructions are pretty barebones to start with. They'll be expanded as more folks install and use Xolo.

Create a Jamf Pro service account

  • This is a Jamf Acct acct that will be used by the xoloserver to connect to the Jamf Pro APIs
    • A future version of Xolo will allow the use of API Clients and roles

Oject Permissions

C = Create, R = Read, U = Update, D = Delete

Objects Permissions
Categories CR
Cloud Distribution Point R
Computer Extension Attributes CRUD
Computers R
External Patch Sources CRU
File Attachments CRUD
Jamf Accounts R
LDAP Servers R
Packages CRUD
Patch Management Software Titles CRUD
Patch Policies CRUD
Policies CRUD
Scripts CRUD
Smart Computer Groups CRUD
Static Computer Groups CRUD

Action Permissons

  • Send Computer Remote Command to Install Package
  • View MDM command information in Jamf Pro API

Create a Title Editor service account

  • This is a Title Editor acct that will be used by the xoloserver to connect to the Title Editor API

Permissions and access

  • Account Type: API Only
  • Permissions: Read and Write Patch definitions

Configure Jamf Pro to see your Title Editor instance as an External Patch Source

  • Note the display-name of that patch source in Jamf, you'll need it to configure the server

Find a Mac to host the server

  • Any recent version of macOS should work

Get your SSL certificate and key

  • You need an SSL certificate (or certificate-chain) and matching private key for your server hostname, in .pem format
  • Certificates from known Certificate Authorities should work as is.
  • If you create a self-signed cert, xadm users will need to set 'Verify SSL Cert' to false in their configuration

Get your package-signing identity from developer.apple.com

  • Needed to sign the xolo-client-data.pkg and possibly other packages depending on server config

  • You may need to create an account at developer.apple.com

  • Note the 'common name' of the identity, it will be needed for server confit

    • It looks like Developer ID Installer: Your Company (123iDentifyer456)

  • Store the identity (a cert and key) in a stand-alone keychain file.

    • Note the password to unlock the keychain, it will be needed for server config

Install the package-signing keychain on the Xolo server

  • It must stored at /Library/Application Support/xoloserver/xolo-pkg-signing.keychain-db

Install ruby 2.7 or higher

  • xoloserver will not work with the OS-supplied version of ruby, and even if it did, it isn't recommended.
  • There are many ways to install ruby, the most common being homebrew.
  • xoloserver has been tested up to ruby 3.3. The current version 3.4 should work fine. Please let us know if not!
  • Make sure you know where your ruby is installed, and where it expects gems (3rd party libraries) to be installed

Install the xolo-server gem

  • gem install xolo-server
    • Add cli-options as needed for your ruby installation (see gem help install)
    • This should install all dependencies
    • By default, the xoloserver executable will probably go into /usr/local/bin

Configure the xoloserver

  • Run sudo xoloserver config --help to see all possible configuration options and full descriptions/documentation
    • That help output is available here in the wiki
    • Set values with sudo xoloserver config --set --config-key 'config value' [--config-key 'config value']
    • Required values before you can run the server are:
      • --ssl-cert
      • --ssl-key
      • --admin-jamf-group
      • --pkg-signing-keychain-pw
      • --pkg-signing-identity
      • --jamf-hostname
      • --jamf-api-user
      • --jamf-api-pw
      • --upload-tool
      • --ted-patch-source
      • --ted-hostname
      • --ted-api-user
      • --ted-api-pw

Sensitive values in xoloserver config

Some items in the server config are sensitive, such as passwords and keys. Those values can be specified in four different ways

  • If the value starts with a pipe '|' the rest of the line is treated as a command and options to be executed, and the value to be used will be read from the standard output of the command.

    • This is useful when secrets are stored in a secret-management tool
    • |/path/to/secret-keeper-tool --read password --from xolo-jamf-api-credentials will run everything after the pipe, using the output as the value

  • If the value is a path to a file, and that path exists on the server and is executable, the path is executed and its standard output is used as the value

    • This is similar to the above, but the executable cannot take any commandline options
    • The executable file cannot have any permissions for 'group' or 'other'. i.e. mode 0700 or 0500 (or 0100)
    • /path/to/jamf-api-pw-tool will run that command exactly, using the output as the value, IF the file is executable.

  • If the value is a path to a file, and that path exists on the server and is NOT executable, the file is read and its contents are used as the value.

    • The readable file must have mode 0600, '-rw-------`
    • /path/to/jamf-api-pw will read that file, using the contents as the value, IF the file is readable but not executable.

  • If none of the above are true, the value stored in the xoloserver config file is used directly.

    • The xoloserver config file /Library/Application Support/xoloserver/config.yaml will have mode 0600

Sensitive items are never shown in the output of xadm server-status (only available to server admins) - they are replaced with <private>.

For configuration debugging, they can be seen on the xolo server machine by running xoloserver config --expand which must be done as root (all use of xoloserver must be done as root)

Backups

Make sure /Library/Application Support/xoloserver is backed up regularly, so that you can restore configuration, as well as title and version data in case of catastrophe. Use Time Machine or whatever backup solution you have available in your environment.

Install a LaunchDaemon plist to run the server automatically.

An example plist is available in the data directory of the xolo-server gem

In that plist, you 'll a commented section recommending you set the Environment Variables PATH and GEM_PATH as appropriate, so that all executables and installed ruby gems will be loadable.

Run the server!

Load the launchd plist, and the server should start up!

Watch the log file at /Library/Application Support/xoloserver/logs/xoloserver.log to look for errors or problems, or just to watch the activity.

To see if its running, go to another machine on the same network and run curl https://your-xoloserver.company.com/ping - it should respond with pong

Clone this wiki locally
⚡