Installation Guide

This guide describes how to install orcharhino using one of several different methods.

Note

orcharhino is available through a subscription model. Please contact us about getting access.

Important

ATIX supports orcharhino installations on CentOS 7, Red Hat Enterprise Linux 7, and Oracle Linux 7. However, as of this writing, both the orcharhino OVA file, as well as the ATIX supplied Kickstart files are CentOS specific. For RHEL and Oracle installations, go straight to the Prerequisites and System Requirements section.

For orcharhino on CentOS installations, choose one of the two following methods:

If orcharhino is to be installed within a VMware vSphere (version 6.0 or greater) environment, you should perform an orcharhino appliance installation. This will use an open virtual appliance (OVA) to create the orcharhino host in VMware and automatically launch the installation.

Note

An open virtual appliance (OVA) is also referred to as an open virtualization format template (OVF). From a user perspective the terms “OVA”, “OVF”, and “Appliance” can all be viewed as roughly interchangeable. (An OVF is really a standardized collection of files, that may be contained within a single OVA file.)

Alternatively, a Kickstart installation will use a Kickstart file (provided by ATIX) along with a CentOS installation media (available online), to install CentOS on the host orcharhino will run on. This will work in virtually any scenario including bare metal installations.

Both installation methods converge with the main installation steps below. Either way, you should start by carefully reading the prerequisites and system requirements.

The installation guide contains the following subsections:

Prerequisites and System Requirements

This subsection of the installation guide provides the prerequisites for the various orcharhino installation methods. Regardless of which installation method you use, you should read all of the general requirements, the system requirements, the OS requirements, and the network requirements.

If you are performing an orcharhino appliance installation you will also need to read the appliance requirements. If you are performing a Kickstart installation, read the Kickstart requirements instead. If you are installing orcharhino on RHEL or Oracle Linux, pay particularly close attention to the OS requirements.

General Requirements

Important

We recommend installing orcharhino on a virtual server. Amongst other advantages this will allow for snapshot creation for backups. Optionally, orcharhino can also be installed on a bare metal system.

Regardless of your chosen installation method, you will need the following:

  • The host orcharhino will run on (see system requirements below).

  • An orcharhino activation key (provided by ATIX) used to register the orcharhino host.

    Note

    Please contact us about receiving an orcharhino activation key.

  • A browser (usually on some secondary device able to resolve a route to the orcharhino host).

  • A working internet connection (either directly or via an HTTP proxy).

    Note

    Offline installations are possible, but well beyond the scope of this guide. If you need to perform an offline installation, please contact us.

  • A network infrastructure set up for orcharhino usage (see network requirements below).

System Requirements

Regardless of whether it is virtual or bare metal, the system orcharhino will run on, must meet the following requirements:

Minimum

Recommended

OS

CentOS 7, RHEL 7, Oracle Linux 7 (See also OS requirements below.)

CPU

4

8

RAM

12 GB

32 GB

HDD 1 (/)

30 GB

50 GB

HDD 2 (/var)

~ 40 GB for each CentOS/RHEL/Oracle distribution

~ 80 GB for each Debian distribution

~ 500 GB (or as appropriate) if you plan to maintain additional repositories or keep multiple versions of packages

Important

The above system requirements explicitly call for two hard drives. One hard drive will be used for the root partition, and the other for the data repositories. This separation is essential for the creation of snapshots and backups, and the Kickstart files provided by ATIX will not work with a single drive system.

Note

For orcharhino appliance installations, you will be asked to choose from a range of possible system specs when you instantiate your OVA. For this installation only, HDD 2 comes in a fixed size of 50 GiB. However, this partition is then extended with a third hard drive of arbitrary size, which is dynamically created during the OVA instantiation.

Warning

It is worth allocating sufficient hard drive resources from the outset. Running out of space for your data repositories during regular orcharhino usage can lead to significant pain.

OS Requirements

ATIX supports orcharhino installations on CentOS 7, Red Hat Enterprise Linux 7, and Oracle Linux 7.

Note

Customers will always receive an orcharhino activation key specific to the chosen platform. Once your orcharhino host is registered with ATIX, it will receive both the package sources for orcharhino, as well as those for the relevant platform, directly from ATIX. The platform packages made available by ATIX are updated regularly.

As of this writing, the orcharhino OVA file, as well as the Kickstart files provided by ATIX will only work for orcharhino on CentOS installations.

Customers who want to install orcharhino on RHEL or Oracle Linux will need to provide a functioning base system of their chosen platform, that adheres to the system requirements above. Once this base system is available, RHEL and Oracle customers will need to download the install_orcharhino.sh script (available for download from ATIX), and follow the instructions for manually launching the orcharhino installation below.

Note

Please contact us to receive the needed download links.

Warning

When installing orcharhino on RHEL or Oracle Linux, it is up to customers to ensure that they have any RHEL or Oracle subscriptions that they may be required to have! Your orcharhino subscription does not include any RHEL or Oracle subscriptions for the underlying platform. If you need help obtaining the relevant subscriptions, or have questions on how to use your existing subscriptions, please contact us.

Network Requirements

Important

orcharhino works best when it is allowed to “manage” the networks it will deploy hosts to. Here, “managed” means that orcharhino will act as DHCP, DNS, and TFTP server for those networks. Allowing orcharhino to manage networks in this way is optional, but should be considered when planning your orcharhino installation. If you have any questions, please contact us.

The following ports have to be open to operate orcharhino on your network (at least if you intend to use the corresponding service):

Port

Protocol

Required for

53

TCP / UDP

DNS server

67,68

UDP

DHCP server

69

UDP

TFTP server

80

TCP

Web server

3000

TCP

Web application server (internal)

3306

TCP

MySQL database server

443

TCP

HTTPS Web server

5910- 5930

TCP

VNC server

5432

TCP

PostgreSQL database server

8140

TCP

Puppet server

8443

TCP

Smart proxy server

8000

TCP

Unattended host provisioning

8015

TCP

Only during the installation

Appliance Requirements

If you are performing an orcharhino appliance installation you will require the following:

  • VMware vSphere (version 6.0 or greater).

  • The orcharhino OVA file (available for download from ATIX).

    Note

    Please contact us to receive the needed download links.

Kickstart Requirements

If you are performing a Kickstart installation you will require the following:

  • The Kickstart file (available for download from ATIX).

    Note

    Please contact us to receive the needed download links.

    Note

    ATIX maintains two different Kickstart files depending on what hard drives you are using:

    • orcharhino_centos_sdX.ks to install CentOS on a host with SATA disks (/dev/sdX)

    • orcharhino_centos_vdX.ks to install CentOS on a host with VirtIO disks (/dev/vdX)

  • A CentOS 7 installation media.

    Note

    CentOS ISO images can be obtained here: https://www.centos.org/download/

Appliance Installation Steps

This subsection of the Installation Guide provides step-by-step instructions for the orcharhino appliance installation in a VMware environment. It presumes some prior experience using VMware’s vSphere client. The orcharhino appliance contains a parametrised but otherwise preconfigured CentOS 7 base system that significantly simplifies the deployment and installation process.


  1. If you have not yet done so, download the latest orcharhino OVA file to your local client PC (see the appliance requirements above).

  2. Open the VMware vSphere client in a browser on your local client PC.

    Note

    The screenshots below may differ depending on whether you are using the Flash or HTML5 based vSphere client, as well as on your exact vSphere version.

  3. Right-click on your datacenter, cluster, or host and select Deploy OVF Template.

  4. On the Select an OVF template screen:

    Select OVF Template
    1. Select Local file (1).

    2. Click the Choose Files button (2).

    3. Select the orcharhino OVA file you downloaded in step 1.

    4. Click the Next button (3) once you are done.

    Note

    It is also possible to enter the OVA download link directly. However, this is not recommended since it has been prone to download failures caused by random network effects.

  5. On the Select a name and folder screen:

    Select a Name and Folder
    1. Enter the Virtual machine name (1) for your orcharhino. If in doubt, use the FQDN or the hostname you want to use for your new orcharhino.

    2. Select a location for the new virtual machine.

    3. Click the Next button (2) once you are done.

  6. On the Select a compute resource screen:

    Select a Compute Resource
    1. Select a host or cluster.

    2. Click the Next button (1) once you are done.

  7. On the Review details screen:

    Review Details
    1. Check your settings.

    2. Click the Next button (1) once you are done.

  8. On the Configuration screen:

    Configuration
    1. Select one size that suits you best by looking at the description of each option.

    2. Click the Next button (1) once you are done.

  9. On the Select storage screen:

    Select Storage
    1. Select a hard disk format for the Select virtual disk format field (1).

      Note

      Choosing “Thick Provision” will take some time for the storage space to be allocated.

    2. For the VM Storage Policy field (2), select a data store or data store cluster.

    3. Click the Next button (3) once you are done.

  10. On the Select networks screen:

    Select Networks
    1. Select an available network from the Destination Network field (1).

    2. Do not change the default values under IP Allocation Settings.

      Important

      For “IP allocation” leave the default value of “Static - Manual”, even if you want to use DHCP. DHCP and IP allocation will be configured during the next step.

    3. Click the Next button (2) once you are done.

  11. On the Customize template screen:

    Customize Template
    1. Enter your orcharhino activation key in the field provided in the Activation Key foldout menu (1).

    2. For the Hostname foldout menu (2), enter the FQDN of your orcharhino.

      Important

      The provided FQDN must contain both a hostname and domain name part. That is, it must contain at least one “dot” (e.g.: orcharhino.example.domain).

    3. If the network you are deploying orcharhino to already has DHCP in it, leave all the fields in the Network Properties foldout menu (3) blank. If you do not already have a DHCP service for this network (which will allow orcharhino to mange DHCP in the network), you will need to fill in all of the fields.

    4. If your organization uses an HTTP proxy to access the internet, fill out all the fields from the Proxy Settings foldout menu (3). If your organization does not use an HTTP proxy, leave the fields blank.

    5. Set the root password of your orcharhino host in the Root Password foldout menu (5). If you leave this field blank, the root password will default to atix. It is highly recommended to set a strong root password.

    6. In the Disk Properties foldout menu (6), you can set the size of your dynamic hard drive. This hard drive will be added to the logical volume containing the /var partition, which will house your content repositories. The default value is set to 50GiB. For more information, see also the system requirements above.

    7. Click the Next button (9) once you are done.

  12. On the Ready to complete screen:

    Ready to Complete
    • You can cancel the entire process by clicking the Cancel button (1).

    • You can go over your configuration (and make changes) by selecting the Back button (2).

    • Click the Finish button (3) to start the deployment.


You can track the progress of your deployment under Recent Tasks in your vSphere client:

Recent Tasks
  1. When the deployment is complete, select the new orcharhino VM in your VMware inventory and click on Launch Remote Console or Launch Web Console.

  2. Now start your new VM (ACTIONS > Power > Power On or similar). This will automatically trigger an orcharhino installation in the console you opened in step 13.

Once your orcharhino appliance has successfully registered with ATIX and installed the main orcharhino installer (this may take some time), a link to the final installer interface will be displayed in the console from step 13.

Note

The link to the installer interface will generally have the following structure: http://<ip_of_orcharhino_vm>:8015

  1. Enter the link in your browser and continue with the main installation steps below.

Kickstart Installation Steps

This subsection of the Installation Guide provides step-by-step instructions on using the Kickstart file (provided by ATIX) to install CentOS on the host orcharhino will run on.

  1. Either virtually mount your CentOS installation media or place it’s physical equivalent in the DVD tray for a bare metal install.

  2. Reboot your system using the installation media. Immediately halt the boot process by hitting tab, and append the following boot option:

    ks=http://<link_to_kickstart_file>
    
  3. Hit enter, and the automatic Kickstart installation will now start. It may prompt you to hit enter from time to time.

  4. Once the Kickstart installation has successfully completed, continue with the following subsection.

Manual Installation Launch

Note

If you are performing an orcharhino appliance installation then the script from this subsection of the Installation Guide will be triggered automatically. Skip this section and go straight to the main installation steps below.

This subsection of the Installation Guide provides usage instructions for the initial install_orcharhino.sh script. The purpose of this script is to register your orcharhino host with ATIX to provide it with the needed orcharhino package repositories. Once successfully registered, the script will also install and launch the main orcharhino installer.

The Kickstart installation from the previous subsubsection will have placed the install_orcharhino.sh script in the /root/ folder on your orcharhino host. It is also available for download from ATIX.

Note

Please contact us to receive the needed download links.

Note

The install_orcharhino.sh script supports multiple options, and requires your orcharhino activation key. For a full list of options and usage instructions, run ./install_orcharhino.sh --help.

It is highly recommended to use the --name option to provide your orcharhino with a FQDN/hostname at this point. To do so launch your script as follows:

/root/install_orcharhino.sh --name='orcharhino.example.domain' <or_activation_key>

The install_orcharhino.sh script will prompt you to confirm the settings you are using for your ACC registration as follows:

install_orcharhino.sh: You are about to register to ACC using the following settings:
install_orcharhino.sh:   orcharhino activation key: '<or_activation_key>'
install_orcharhino.sh:   orcharhino FQDN: 'orcharhino.example.domain'
install_orcharhino.sh:   orcharhino IP address: '<or_ip_address>'
install_orcharhino.sh: Proceed with these settings? [Yes/No]

Entering anything other than Yes, yes, Y, or y will cause the script to exit without taking any further actions. You can always rerun the script with modified options. You can override the <or_ip_address> setting using the -i/--ip-addr=ADDR option. You can also skip the above confirmation prompt by using the -y/--yes option.

Once you have confirmed the prompt, the install_orcharhino.sh script will automatically install and launch the main orcharhino installer which will display a link to the web interface. It may take some time to reach this point. The link will look something like the following:

http://192.168.121.179:8015/?token=4f27b9328cc0ead7d499c93f34ec9bda5d26e7b50c4420dc0a80dcc04adcf9dd

Point your browser at the provided link and continue with the following subsection.

Main Installation Steps

This subsection of the Installation Guide provides step-by-step instructions for using the web interface of the main orcharhino installer.

You should have accessed this interface as the final step specific to your chosen installation method (appliance installation or Kickstart installation above).


  1. On the Basic Configuration screen:

    Basic configuration
    1. Enter the password that your orcharhino admin account will use into the fields provided (1).

    2. Enter an email where the orcharhino administrator can be reached into the Admin email field (2).

    3. Finally enter the context that will be used for the initial configuration of your orcharhino host into the Organization and Location fields (3).

      Warning

      Setting an Organization or Location that contains white space or non ascii characters has been known to cause bugs. Please choose a single word that does not include umlauts or special characters.

    4. Click the Next button (4) once you are done.

  2. On the HTTP Proxy screen:

    HTTP Proxy configuration
    1. Select the Use HTTP Proxy check mark (1), and fill in your HTTP proxy’s data in the fields provided (2-5).

      Note

      If your organization does not use an HTTP proxy server, ignore this step.

    2. Click the Next button (6) once you are done.

  3. On the Networking Capabilities screen:

    Filled network capabilities

    Important

    We recommend allowing orcharhino to manage DHCP, DNS, and TFTP on the subnet where it will manage hosts (see also network requirements above). Follow all of the steps below for this setup. However, if there is good reason, then deselect the corresponding services (1), (6), and/or (11) and disregard steps (2a), (2b), and/or (2c).

    1. Configure orcharhino’s DHCP capability (1).

      1. For the DHCP interface field (2), select the interface to the network on which orcharhino will be deploying hosts. (We will refer to this network as the internal network hence forth).

        Note

        The orcharhino installer will try to guess sensible values for the input fields (3), (4), and (5) based on your DHCP interface selection. We highly recommend double checking these auto-generated values before continuing.

      2. For the DHCP gateway IP field (3), enter the gateway IP address that hosts managed by orcharhino will use (on the internal network). (The auto-generated value will be the default-gateway on the selected interface.)

      3. For the DHCP nameservers field (4), enter the IP address that hosts managed by orcharhino will use to resolve DNS queries. (If Manage DNS (6) is selected this will be the IP address of the orcharhino host on the internal interface, this is also the auto-generated value).

      4. For the DHCP range field (5), enter the range of IP addresses that is available for hosts managed by orcharhino, on the internal network. (The installer will try to calculate the largest free range within the IP network, by excluding its own address, as well as those of the gateway and the configured name server. It is not verified automatically, whether any other hosts already exist within this range.)

    2. Configure orcharhino’s DNS capability (6).

      1. For the DNS interface field (7), select the interface to the internal network. The same interface you used for the DHCP interface field (2).

        Note

        The orcharhino installer will try to guess sensible values for the input fields (8) and (9) based on your DNS interface selection and the systems resolv.conf file. We highly recommend double checking these auto-generated values before continuing.

      2. For the DNS forwarders field (8), enter the IP address of your organizations DNS server, (or of some external DNS server, that can be reached from the orcharhino host). (The installer tries to pre-fill this field with a DNS server from the system’s resolv.conf file.)

      3. For the DNS reverse field (9), enter the net ID part of the IP address of the internal network in decimal notation, with the byte groups in reverse order, followed by .in-addr-arpa. (For example, a network address of 192.168.0.0/24 would turn into 0.168.192.in-addr-arpa; pre-filled with the appropriate value for the chosen interface).

      4. For the DNS TTL (Time to Live) in sec field (10) enter the desired value.

    3. Select/deselect orcharhino’s TFTP capability (11).

    4. Click the Next button (12) once you are done.

  4. On the Operating Systems screen:

    Operating System configuration
    1. Select any operating systems (1) you want your orcharhino to be preconfigured for.

      Important

      If you want to be able to deploy SUSE Linux Enterprise Server (SLES) hosts with your orcharhino, you will need to perform additional steps at the end of the installation process to set up your SLES installation media.

    2. Click the Next button (2) once you are done.

  5. On the Configuration Management screen:

    Configuration management selection
    1. Puppet support (1) is a required orcharhino dependency and is always selected.

    2. If you also want Ansible support select the relevant check box (2).

    3. If you also want Salt support select the relevant check box (3).

    4. Click the Next button (4) once you are done.

  6. On the Compute Resources screen:

    Compute resource selection

    Warning

    The Proxmox compute resource plugin is incompatible with other compute resource plugins. Please choose either Proxmox or one or more other compute resources.

    1. Select any Compute Resource Plugins (1), if you want orcharhino to support those compute resources.

    2. Click the Next button (2) once you are done.

  7. On the Plugins screen:

    Plugins selection
    1. Select any Plugins (1) you want installed on your orcharhino. (See Plugin Guides for more information).

    2. You can go over your configuration by selecting the Previous button (2).

    3. Click the Finish button (3) once you are done. This will trigger the installation process (which will display console output in the browser window, and may take some time).


Once orcharhino has successfully installed, the installer will display something similar to the following:

Web installer finish
  • Click the button provided (1) to go to orcharhino’s login page.

  • Log in using the admin user, along with the password you set up during step 1 above.

  • Enjoy your brand new orcharhino installation!

  • If you are unsure how to continue, have a look at the first steps guide.

  • If you want to deploy SLES hosts, make sure you also set up some SLES media.

Setting up SLES Media

Note

This section presumes you have selected at least one SLES variant from the list of operating systems during step 4 of the main installation steps above. If you did not select an entry like “SUSE Linux Enterprise Server <version>” from the list of operating systems, ignore this section.

The installation media for SUSE Linux Enterprise Servers (SLES) are not generally available by public mirror. (Instead, SLES ISO files can be obtained from SUSE). As a result, it is necessary to add any SLES media you might need to your orcharhino manually. (You will not be able to deploy any SLES hosts out of the box). This section will describe how to add SLES media. This section assumes you have access to any relevant SLES media in the form of ISO files.

If you navigate to the installation media page in the interface of your newly installed orcharhino, you will find that the entries for your SLES media are already created:

SLES installation media

However, the paths displayed for your SLES media are currently pointing at non existent locations. What we need to do, is to unpack our SLES ISO files, to the location specified by these paths. The following step-by-step instructions will illustrate the process for the SLES 11 medium (the process for other SLES versions is analogous, all commands are run as root on the orcharhino host).

  1. Make sure your SLES ISO file is present on your orcharhino host. (How best to move files to your orcharhino host is dependent on your exact setup).

  2. Create the directory for your SLES medium:

    mkdir -p /var/www/html/pub/installation_media/sles/11sp4/
    
  3. Extract your SLES ISO to the newly created directory.

    1. Install p7zip for ISO extraction:

      yum install p7zip p7zip-plugins
      
    2. Perform the extraction:

      7z x <path_to_sles_iso> -o'/var/www/html/pub/installation_media/sles/11sp4/'
      
    3. Make sure the permissions on your extracted files will allow Apache to read them:

      chmod -R go+X+r /var/www/html/pub/installation_media/sles/11sp4/*
      
  4. (optional) Make sure your extracted files are visible (in a browser) at the following location:

    http://orcharhino.<domain>/pub/installation_media/sles/11sp4/
    
  5. (optional) Remove the SLES ISO file from your orcharhino host (only the extracted files are needed).

Note

Alternatively, you can also host your SLES ISO file on some arbitrary web server, reachable from your orcharhino host (the ISO file needs to be extracted on the web server). Then, simply change the link of the SLES medium’s orcharhino entry, to point at your web server location.