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
  • Oject Permissions
  • Action Permissons
• Create a Title Editor service account
  • Permissions and access
• Configure Jamf Pro to see your Title Editor instance as an External Patch Source
• Find a Mac to host the server
• Get your SSL certificate and key
• Get your package-signing identity from developer.apple.com
• Install the package-signing keychain on the Xolo server
• Install ruby 2.7 or higher
• Install the xolo-server gem
• Configure the xoloserver
  • Sensitive values in xoloserver config
• Install a LaunchDaemon plist to run the server automatically.
• Run the server!

• 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

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

Objects	Permissions
Categories	CR
Computer Extension Attributes	CRUD
Computers	R
External Patch Sources	CRU
File Attachments	CRUD
Packages	CRUD
Patch Management Software Titles	CRUD
Patch Policies	CRUD
Policies	CRUD
Scripts	CRUD
Smart Computer Groups	CRUD
Static Computer Groups	CRUD

• Send Computer Remote Command to Install Package

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

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

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

• Any recent version of macOS should work

• 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

• 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

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

• 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

• 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

• 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

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)

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.

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