Installation Guide

This guide describes how to install orcharhino using the “Kickstart + orcharhino web installer” method. (Hence forth the orcharhino web installer will be referred to as orcharhino installer or simply installer). In other words, we will use a Kickstart file (provided by ATIX) to install CentOS on the host orcharhino will run on, and the orcharhino installer (provided directly on the CentOS host installed via Kickstart) to install orcharhino itself.

Note

orcharhino is available through a subscription model. Please get in Contact with us to get access to the Kickstart files and the orcharhino installer to start the installation of orcharhino.

The installation guide contains the following subsections:

Prerequisites and System Requirements

In order to follow the installation process from this guide, you will require the following:

  • The host system orcharhino will run on (see the table below for system requirements).
  • A CentOS installation media.
  • The Kickstart file (provided by ATIX) used to install CentOS on the host orcharhino will run on.
  • A password (provided by ATIX) to unpack the orcharhino installer.
  • An activation key (provided by ATIX) used to authenticate the orcharhino host.
  • A browser (normally on some secondary device able to resolve a route to the orcharhino host).
  • And finally, a working internet connection.

Note

A CentOS minimal installation ISO image can be obtained here: https://www.centos.org/download/

Note

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

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

  Minimal Recommended
Operating System CentOS 7 (as provided by the ATIX Kickstart file)
CPU 4 8
RAM 12 GB 32 GB
HDD 1 (/) 30 GB 50 GB
HDD 2 (/var)

~ 40 GB for each CentOS/RHEL 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.

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.

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

Installation Steps

This subsection of the Installation Guide provides step-by-step instructions on all the steps needed to install orcharhino (as well as the CentOS operating system it will run on). In particular, the process involves installing CentOS via Kickstart file, unpacking the orcharhino installer shipped with this Kickstart installation, and finally running the orcharhino web installer itself.

Using the Kickstart File

This subsubsection 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.

Note

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

  • orcharhino-wi-el7-sdX.ks to install CentOS on a host with SATA disks (/dev/sdX)
  • orcharhino-wi-el7-vdX.ks to install CentOS on a host with VirtIO disks (/dev/vdX)
  1. Either virtually mount your CentOS installation media, (see also Prerequisites and System Requirements above) 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://<path_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 Unpacking the orcharhino Installer below.

Unpacking the orcharhino Installer

This subsubsection of the Installation Guide provides step-by-step instructions on unpacking the orcharhino installer provided by your Kickstart installation.

  1. Execute the orcharhino installation script on your newly installed CentOS host. (See also Using the Kickstart File above). It can be found here:

    /usr/share/orcharhino-installer/orcharhino-installer.sh
    
  2. When prompted, enter the password provided by ATIX (see also Prerequisites and System Requirements above).

  3. The orcharhino-installer.sh script will display the hyperlink to the orcharhino web installer via console output once it has successfully executed. (This may take some time).

  4. Copy the link into your browser (see also Prerequisites and System Requirements above) and continue with the following subsubsection.

Using the orcharhino Installer

This subsubsection of the Installation Guide provides step-by-step instructions on using the orcharhino installer once you have unpacked it.

When you enter the link from the previous step in your browser of choice, you will be greeted by the basic configuration page of the installer (the first of several steps):

Basic configuration
  1. Enter the fully qualified domain name (FQDN) that your orcharhino host should use on your network into the Hostname (FQDN) field (1).

  2. Register with ATIX (to gain access to our download server)

    1. Enter the activation key you received from ATIX into the ATIX Activation Key field (2).
    2. Click the Register to ATIX button (3)

    Note

    Registration may take a minute. While you wait the remaining fields (4) on the basic configuration page can be filled in. Once registration is successful the Register to ATIX button (3) will turn green, and read Registration: done! as follows:

Filled basic configuration
  1. Enter the password for the administrator (admin) account of your orcharhino installation 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). (See also: The Context Menu paying particular attention to Usage and Features)
  4. Hit the Next button (4) once you are done.

The networking capabilities page (the following screenshot has example values filled in) will now appear:

Filled network capabilities
  1. We recommend allowing orcharhino to manage DHCP, DNS, and TFTP on the subnet where it will manage hosts. (Follow all of the steps below for this setup). However, if there is good reason not to do so on your organizations infrastructure, then deselect the corresponding services (1), (6), and/or (10) (and disregard the corresponding steps below).

  2. Configure orcharhino’s DHCP capability.

    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.)

  3. Configure orcharhino’s DNS capability.

    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. Select/deselect orcharhino’s TFTP capability (10).

  5. Hit the Next button (11) once you are done.

The http proxy page (the following screenshot has example values filled in) will now appear:

HTTP Proxy configuration
  1. If your organization does not use an HTTP proxy server, ignore this step. Otherwise, select the Use HTTP Proxy check mark (1), and fill in your HTTP proxy’s data in the fields provided (2) to (5).
  2. Hit the Next button (6) once you are done.

The operating systems page (the following screenshot has example values filled in) will now appear:

Operating System configuration
  1. Select any operating systems (1) you want your orcharhino to be preconfigured for.
  2. Hit the Next button (2) once you are done.

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. (See Setting up SLES Media below).

The plugin selection page (the following screenshot has example values filled in) will now appear:

Plugin selection
  1. Select any Generic Plugins (1) you want installed on your orcharhino.
  2. Select any Compute Resource Plugins (2), if you want orcharhino to support those compute resources. (See also: Compute Resources Guide).
  3. You can go over your configuration by selecting the Previous button (3).
  4. Hit the Finnish button (4) 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 the following:

Web installer finish
  • Click the button provided to go to orcharhino’s web interface. (See also Management UI).
  • Log in using admin, and the “Admin password” you set via the installer.
  • Enjoy your brand new orcharhino installation!

Setting up SLES Media

Note

This section presumes you have selected at least one SLES variant from the list of operating systems in the orcharhino installer (see Using the orcharhino Installer above). If you did not select an entry along the lines of “SUSE Linux Enterprise Server <version>” from the list of operating systems in the orcharhino installer, you can 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 (see also Installation Media) in the web interface (see also Management UI) 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-host>.<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 mediums entry in orcharhino, to point at your web server location. (See Installation Media for more information).