Skip to content

Home

Jump to bottom
Roni Väyrynen edited this page Jan 15, 2023 · 6 revisions

Installation

For the most usecases using default settings is completely fine to get Xen Orchestra up and running. Below are some of the most common scenarios you might want to look into before running installation.

Start off by copying the sample configuration if not done already:

cp sample.xo-install.cfg xo-install.cfg

HTTPS

There's few different ways to enable HTTPS for Xen Orchestra.

ACME (eq. Let's Encrypt), automatically created by Xen Orchestra

Edit xo-install.cfg with your preferred text editor and make sure following variables are set:

ACME="true"
ACME_DOMAIN="your.domain.tld"

Additionally you can set ACME_EMAIL="[email protected]" to receive notifications related to your certificate.

Enabling ACME overwrites some other configuration options so that it works properly, these are:

  • PORT is set to 80
  • AUTOCERT is set to true
  • Certificate and Key paths are set to ./certificate.pem and ./key.pem, meaning they will be located in same directory with xo-server config.toml file.

Certificate will be generated when XO is accessed first time from browser with domain set in configuration. When this is done for the first time, the page will load slightly longer due to certificate being generated.

Check these if certificate generation doesn't work properly:

  • XO instance needs to be publicly accessible with domain and ports 80/443 allowed for certificate generation to work.
  • If certificate/key paths were set before and there are existing files, XO won't generate a new ACME certificate. Stop xo-server, remove/rename these files and restart xo-server.

Self-signed certificate, automatically created by Xen Orchestra

Edit xo-install.cfg with your preferred text editor and make sure following variables are set:

PORT="443"
CONFIGUPDATE="true"
PATH_TO_HTTPS_CERT=$INSTALLDIR/xo.crt
PATH_TO_HTTPS_KEY=$INSTALLDIR/xo.key
AUTOCERT="true"

Now whenever install/update is ran with xo-install.sh, after xo-server service is started a new certificate/key pair is created to /opt/xo/xo.crt//opt/xo/xo.key and Xen Orchestra will use them. AUTOCERT option will ensure that these files are autogenerated if they do not exist.

Self-signed certificate, manually created

Generate certificate/key pair with openssl:

mkdir -p /etc/ssl/xo
openssl req -nodes -x509 -newkey rsa:2048 -keyout /etc/ssl/xo/key.pem -out /etc/ssl/xo/cert.pem -days 365 -subj "/CN=xen-orchestra"

Edit xo-install.cfg with your preferred text editor and make sure following variables are set:

PORT="443"
CONFIGUPDATE="true"
PATH_TO_HTTPS_CERT="/etc/ssl/xo/cert.pem"
PATH_TO_HTTPS_KEY="/etc/ssl/xo/key.pem"

Run install/update with xo-install.sh

Use existing certificate

If you have existing certificate you want to use, just make sure following settings are present in xo-install.cfg:

PORT="443"
CONFIGUPDATE="true"
PATH_TO_HTTPS_CERT="/path/to/your/certfile"
PATH_TO_HTTPS_KEY="/path/to/your/keyfile"

Run install/update with xo-install.sh

Note that if using non-root user in xo-install.cfg, this user needs to have appropriate read (or read/write if AUTOCERT is set to true) permissions to directory where defined certificate/key are located.

Non-root user

Script fully supports using a non-root user to run Xen Orchestra and will take care of everything for you. Couple things to note: script still needs to be run as root and any SELinux related permissions aren't modified.

Just change this in xo-install.cfg:

XOUSER="username"

It can be existing user or new one. It'll be created if missing.

Additionally you might want to set sudo settings in xo-install.cfg so that you can mount remotes in Xen Orchestra running with non-root user:

USESUDO="true"
GENSUDO="true"

Running on non supported OS/Architecture

By default script refuses to run on any other than list of supported operating systems, versions and architecture. This doesn't mean script won't work on some other rpm/deb variant, this is simply to keep the list manageable as there's very little reasons to install Xen Orchestra on an unsupported OS.

All that being said, there is a method to in xo-install.cfg to disable the operating system and/or architecture check if you wish to try it out anyway.

OS_CHECK="false"
ARCH_CHECK="false"

Custom non supported Xen Orchestra configuration

Script supports a set of configuration options defined in xo-install.cfg. Some of these edit the final xo-server configuration file (by default stored in $HOME/.config/xo-server/config.toml). In some cases you might've chosen to edit this configuration by hand but still want to run updates with xo-install.sh. With default settings, this configuration file would be overwritten with every update. There is option to disable this behaviour and keep existing configuration file:

CONFIGUPDATE="false"

Update

Script itself will update itself (starting from commit 03f5ad9) during startup if certain conditions are met:

  • ronivay/XenOrchestraInstallerUpdater has been cloned with git
  • There are no local conflicting changes inside this repository directory
  • There is a newer version of xo-install.sh available at remote

Each Xen Orchestra update operation ran via script will be a completely independent installation excluding /var/lib/xo-server and /var/lib/redis data directories which are reused. Installations are stored in $INSTALLDIR/xo-builds directory and active installations are symlinked to $INSTALLDIR/xo-server and $INSTALLDIR/xo-web.

If you change anything in xo-install.cfg after already running installation, you need to run update for those changes to become active.

Rollback

Since each update is a complete installation, we have the possibility to do rollback in case the latest build failed.

By default 3 installations will be preserved to which you can rollback if needed. This can be changed in xo-install.cfg if you want to preserve more/less:

PRESERVE="3"

Debug

Xen Orchestra build fails, something else fails, what to do?

Xen Orchestra is actively developed against https://github.com/vatesfr/xen-orchestra repositories master branch, from where the source is pulled by this script to be built. Due to this nature, it's possible that from time to time the build fails, simply because there is some recent change which breaks something. If it's the Xen Orchestra build that failed, you might want to try again later. If fail happens at any other stage it's most likely because of the script itself. Either way please file issues to this scripts repository if you're not 100% sure it's purely a Xen Orchestra issue.

Script stores quite a verbose logfile which by default is stored in <script-directory/logs. Logfiles are named with timestamp which matches the script execution time. You should be able to pinpoint the exact command and error that it produced. If you think the error is common, please file an issue to this repository.

If needed, you can rollback to a previous installation with the scripts rollback feature.

xo-cli

Script will automatically install xo-cli. It is available in /usr/local/bin/xo-cli. To register xo-cli with XO installation, run:

xo-cli --register <xo web address> <username> <password>

example: xo-cli --register http://127.0.0.1 [email protected] admin

Clone this wiki locally