Install Outrun

1 Overview

Outrun is a toolset for Enterprise Linux (CentOS, Red Hat, Oracle) that automates the installation and management of Oracle databases. More info can be found at Outrun Overview

If you read this as a PDF document, note that the Outrun Wiki may be more up to date. Check http://outrun.nl.

You are also recommended to read the Release Notes before proceeding as they may contain invaluable information about existing issues and solutions.

2 Disclaimer

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Note that Outrun currently is in Beta stage and not ready for production purposes - however, the design and architecture is targeted to eventually be used for production environments.

3 Preparation

3.1 Before you start

The purpose of Outrun is to run Oracle databases. Because Oracle software is copyrighted, it is NOT included with Outrun (which is 100% open-source with some freeware components). This means you need to download Oracle software yourself from Oracle (which requires a registration). Outrun provides a function to create an ISO installer image, which you only need to run once for a given version of the Oracle software. Without these Oracle files, Outrun will not be of much value.

3.2 Installation Methods

Outrun provides a few methods to install new systems:

• Boot and install from ISO image (default, CentOS 6.x only)
• Install via PXE server (advanced, other distributions and versions)
• Install on existing Linux system via YUM repositories (experimental, mileage may vary)

The ISO image is based on CentOS 6. The PXE install method also supports Red Hat Enterprise Linux (RHEL) and Oracle Enterprise Linux (OEL), versions 6 and 7.

If you need RHEL or OEL based installations, first create a PXE staging server on a standard CentOS Outrun system (described later).

Outrun is designed to install on VMware. However, it should run just fine on physical servers or other hypervisors as long as a few conditions are met.

The rest of this manual is assuming you run VMware (either Workstation/Fusion or vSphere/ESX) but some notes explain differences when installing bare metal or alternative hypervisors.

3.3 Outrun ISO image contents

The Outrun ISO image is based on CentOS-6.7-x86_64-minimal.iso with the following changes:

• Some unneeded components from the original image are removed (such as SElinux and some firmware packages)
• A few RPM packages not on the default install are added for enabling the postinstall process
• The boot process is changed such that it will directly start up the CentOS Anaconda installer using a kickstart file (without going through a manual setup process)
• 2 “squashfs” images are added:
  • /squash/outrun-<version>-base.squashfs (contains all Outrun packages)
  • /squash/outrun-<version>-centos.squashfs (contains CentOS RPMs required for dependencies of the Outrun packages)
• A bootstrap RPM package (/squash/outrun-bootstrap.rpm ) is added (for preparing and starting up the postinstall process)

The files from /squash/ on the ISO can be found on /opt/squash/ after installation.

3.4 Pre-install checklist

To install Outrun (on a VM), you need:

• A Virtual Machine with a blank bootdisk (x86-64 architecture)
• Bootdisk must be SCSI (not SATA, SAS or anything that does not appear as /dev/sdXX)
• CD-Rom emulation to mount ISO images
• Supported network adapter (presented as "eth0")
• Outrun ISO distribution image
• Oracle installer ZIP files for version 11.2g or 12.1c (or the pre-built Oracle installer ISO image)
• Minimum of 25GiB bootdisk, 40GiB recommended (12c requires more diskspace as well as large RAM configurations, but never more than 40GiB)
• IP Network connectivity (direct or via Network Address Translation)

On a physical server, similar specs but:

• Physically bootable CD drive (or something like ILO hardware emulated CDrom)
• Bootdisk must be supported on Linux as bootable SCSI disk (again, as /dev/sdXX) and you must know how the bootdisk appears if it's not the default /dev/sda

3.5 Preparation

Generic VMware Virtual Machine specifications
Parameter	Setting	Notes
Guest OS version	Red Hat Enterprise Linux 6 64-bit1	Optimal preconfiguration settings
RAM minimum	4GB (Oracle 11c), 5GB (12c)	More memory also requires more swapspace on bootdisk
RAM maximum	Unlimited	More than 16GiB RAM only requires 16GiB swapspace
Network	NAT or Bridged / Shared	NAT on corporate/unsupported networks
NICs	1 (standard) or 2 (RAC)	More NICs are not used by Outrun
VMX File	disk.enableuuid = "TRUE"	Add this line to the virtual machine's VMX file

Network adapter
Platform	Adapter type	Notes
vSphere	VMXNET 3	E1000 works, VMXNET3 has better performance
Workstation/Fusion	E1000	vmxnet not available

Bootdisk
Parameter	Setting	Notes
Disk Size	20GiB	Absolute minimum
	40GiB	Recommended
Boot disk type	SCSI	(no IDE, SAS, SATA or similar)
Boot disk ID	/dev/sda	(SCSI 0:0:0, preferred, default), /dev/sd<X> (optional)
Additional disks	Any	As required for your databases

4 Installation

4.1 Booting for installation

For VMware workstation or VMware Fusion, be aware that you select “install the OS later”.

• Install Operating System from “I will install the OS later”

The other options will fail as the Outrun ISO is not a standard Linux install image.

4.2 Install OS from ISO

Mount the custom Outrun ISO image as VMware “CD/DVD drive 1” and use it to boot the virtual machine.

CD Drive settings on VMware
Workstation
	CD/DVD (SATA)
	Device Status
		[√] Connected
		[√] Connect at power on
	Connection
		[*] Use ISO image	Select Outrun ISO from file system
ESX
	CD/DVD Drive 1
	Device Status
		[√] Connected
		[√] Connect at power on
	Device Type
		[*] Datastore ISO file	Select Outrun ISO from a datastore
	Virtual Device Node	IDE 1:0 CD/DVD Drive 1

4.3 Starting the VM for install

Start the VM and go to the VM console. If the bootdisk is blank, the console will show the install menu:

Outrun for Oracle 0.9 via ISO
Install Outrun system (on empty /dev/sda) Install Linux only (on empty /dev/sda) Destroy boot disk (/dev/sda) Rescue installed system Boot from local drive
[F1] help [F2] requirements [F3] info [TAB] to continue

4.4 Install menu

The Outrun Install menu shows a few options:

• Install Outrun system (default, starts automatically after a few seconds)
• Install Linux only - this gets you a Linux system based on the same disk layout but without the postinstall phase kicked off).
• Destroy boot disk – wipes the first 10 MiB of the bootdisk in order to blank the partition table and the first chunk of data. The rest of the data will still be there but very hard to recover. A blank partition table lets Outrun reinstall as if it was a completely empty disk.
• Rescue – the standard CentOS rescue method. Use for recovering from accidental deletes or systems that refuse to boot.
• Boot from local drive – attempts to boot the existing OS if there is one

4.5 Advanced options

On the boot menu, press F1 for help, F2 for version info and F3 to show requirements.

By entering [TAB] on the boot menu you will see the install command line. Outrun offers a few special parameters that you can provide here:

Installation parameters
Parameter	Description
bootdisk=dev	Allows you to specify a different bootdisk than /dev/sda.
rootpw=<password>	Changes the default root password “outrun” to something else at install time. For improved security.
postinstall=skip	Avoids the initial postinstall phase after the first boot.
preinstall=nocopy	Avoids copying the Outrun squashfs files to /opt/squash
preinstall=shell	Drops into a very basic shell for debugging of the install process. Might help figuring out how your bootdisk appears (or if it does at all)
preinstall=wipe	Similar to the “Destroy bootdisk” menu option. Note that always /dev/sda gets blanked (not the other disks).
outrun=<url>	Copy squashfs images from <url> instead of default
updateurl=<url>	Use <url> for Outrun YUM updates (see Local_Update_Repository)
testurl=<url>	Setup a test repo using URL (for Outrun alpha testing)
localurl=<url>	Setup a local YUM repo using URL and add all packages from this URL after install

4.6 Entering install options

At the Installer menu, by entering [TAB] you will see the install command line. You may add options as mentioned.

A simple help system is provided by pressing [F1] [F2] [F3]:

F1 – Shows install help and options

F2 – Shows installation requirements

F3 – Shows the Outrun version, build etc

TAB - Shows a command line where you can append install parameters. See example below where we use a different root password:

Outrun for Oracle 0.9 via ISO
Install Outrun system (on empty /dev/sda) Install Linux only (on empty /dev/sda) Destroy boot disk (/dev/sda) Rescue installed system Boot from local drive
> vmlinuz initrd=initrd.img ks=cdrom:/ks.cfg rootpw=topsecret_

5 After installation

5.1 Postinstall

Unless disabled, the postinstall runs automatically after the first reboot. The trigger for this is the outrun-bootstrap-*.rpm package that is installed during kickstart install.

To find out how it works, run rpm -qvl outrun-bootstrap to see it's files, and rpm -q --scripts outrun-bootstrap to see what it does during RPM install.

Outrun will switch to a console where it displays progress of the installation. At this point, additional packages will be installed, users created, system settings configured and more. As long as the console does not switch to the login terminal, postinstall is not complete. Just wait a few minutes for it to finish.

The postinstall phase usually takes about 5 minutes or less. During install you will see the output of the installation process. When done, the console will switch to a login terminal and show a message similar to this:

Outrun for Oracle 0.9 on CentOS release 6.6 (Final)
console tty1
localhost login:

Only if you see the “Outrun” login message on the console, the installation is complete.

5.2 Login

If networking is configured automatically then you should be able to use "ssh" to remotely login. If you don't know the IP address or if networking is not configured, login as root via the console.

The console login option should only be needed for getting the IP configuration done as it is a very limited way of doing things.

The normal command line login method is using Secure Shell (SSH) and requires an SSH client and an IP connection to port 22 on the Outrun system.

If your workstation (desktop) is Linux then in nearly all cases the SSH client is a standard, preinstalled feature (if not, install something like "openssh-clients"). On your desktop, open a Shell and on the command line, enter:

ssh root@outrun-hostname.example.com

On OSX, the procedure is similar, open a terminal and run the ssh command.

If your machine is Windows, then SSH is not installed by default. You need an SSH client. The most common used one is PuTTY, however, PuTTY has some issues with correctly displaying the Outrun menu outlines and colors. I recommend using MobaXterm instead - download from MobaXterm download. I also included MobaXterm in Outrun, so if you installed Outrun and IP networking is active, you can get it from theOutrun FTP server.

A nice side effect is that MobaXterm behaves like a real Linux/Unix system and has X-Window graphical support (which may be needed later).

The first time you use SSH on Linux to log in to a new host, you get a warning message:

The authenticity of host 'outrun01 (1.2.3.4)' can't be established.

Answer "yes" to continue.

After entering the root password, you should be able to get a message like this:

Welcome to Outrun for Oracle 0.9 on CentOS release 6.6 (Final) 

This program is distributed in the hope that it will be useful, 
but WITHOUT ANY WARRANTY; without even the implied warranty of 
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
GNU General Public License for more details. 

Help: "man outrun" | Menu: "menu" or "outrun-menu"
# _

If the hostname and/or IP address has been used before (usually after you reinstall the system), you might get a warning message. In Linux:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

In this case, you need to clear the ssh known_hosts entries that are related to this host. The brute force method in Linux:

rm ~/.ssh/known_hosts

This will remove ALL known hosts entries and ask you to verify the authenticity. A more elegant method:

ssh-keygen -R <hostname>
ssh-keygen -R <ip-address>

5.3 Using the Outrun Menu System

You can start the Outrun menu by typing menu or outrun-menu.

A dialog box will show similar to this:

Main Menu
System Configure system Storage Manage Storage Networking Manage networking Power Shutdown & Console options
<OK> <Back> <Help>
Status
Hostname: myhostname.local System: CentOS 6.6 IP: 1.2.3.4

The Outrun Menus are based on Dialog, a very Spartan menu system - but it works even on a text console (without IP networking active yet), is very lightweight and simply gets the job done.

Navigation however can be a bit awkward, so here are a few tips:

ESC

Quit menu immediately

Arrow Up/Down

Work through menu items

PgUp/PgDown

Work through menu items faster - or scroll through larger pieces of text (help etc)

TAB / Shift-TAB

Move between OK/Back options

SPACE

Select/deselect options

ENTER

Same as Submit / OK depending on context

6 Network configuration

6.1 Networking overview

Oracle Database requires a fixed hostname and IP address to work properly. <ref>Not strictly but things get complicated when hostname and/or IP address changes.</ref>

Outrun therefore has a simplified and standardized way of configuring IP networking. It is recommended NOT to use the standard Linux methods (i.e. directly editing the config files, or running system-config tools) unless you know what you are doing. Outrun may overwrite these config files.

Outrun can work with different types of network connectivity. Some installs will be on fully controlled networks where you can configure the DHCP and DNS server to provide valid network configuration to the Outrun host. Other networks might be out of your control for such configuration.

Network types
Network example	DNS services	DHCP services
Dedicated subnet (i.e. test network)	configurable	configurable
Shared LAN (i.e. corporate LAN)	configurable (by request)	maybe configurable
VMware Virtual LAN behind NAT	pooled	forwards external requests only
Uncontrolled	pooled or nonexistent	forwards external requests only

Outrun can work with any of those - but for LANs that don't provide valid DNS hostnames, and, ideally, DHCP services, some manual configuration is required.

6.2 Network parameters

Required network parameters
Item	Methods
IP address, Netmask, Gateway	DHCP	Static (manual)
Hostname	DHCP or DNS	Static (manual)
DNS server & search domain	DHCP	Static (manual)

Optional network parameters
Item	Methods
MTU size (jumbo frames)	Default 1500, configurable
Second Interface IP address, Netmask, Gateway	Auto-configured from DNS
NTP server	DHCP	Static (manual)
DNS server & search domain	DHCP	Static (manual)

6.3 Basic IP settings

You need an IP address on a LAN that is somehow reachable from your desktop (at least via Secure Shell (port 22) and Anonymous FTP (port 20/21), and other ports for other services (such as Oracle connections on port 1521, VNC on 5900 etc). With the IP address you also need a valid netmask and default gateway, and ideally a working DNS server reachable somewhere on the network.

You also need to provide a valid hostname.

The IP address and hostname must not change between reboots. Oracle Clusterware is extremely sensitive to such changes and usually requires complete re-configuration after network changes.

There are basically three sorts of networks that Outrun can work with:

No DHCP services at all

requires static IP configuration

DHCP services using a random, dynamic pool of IP addresses

cannot be used, also requires static IP configuration

DHCP services that provide consistent IP address (and hostname) based on the system's MAC address

can be used (actually this is the preferred method if you plan to run more than one Outrun system)

See Emulate Fixed Address using DHCP for more info on static IP addressing with DHCP.

6.4 DHCP Server

If you want to use a DHCP server on the LAN (note that Outrun provides this if you set it up as such) then it must provide static, consistent IP based on the host's MAC address Outrun is designed to work with a DHCP server on the LAN to which the primary network interface is connected. If DHCP is set up correctly, it will automatically provide:

• IP address
• Netmask
• Default gateway (router)

Some DHCP servers offer more than just the basic IP configuration:

• Hostname (either fixed or dynamic)
• DNS server(s)
• Domain name / Search domains
• NTP (time) server

The traditional way DHCP servers work by providing IP addresses (and maybe hostnames) from a pool of IP addresses. With Outrun (or actually, Oracle) this is problematic as database servers are expected to have fixed IP addresses and hostnames. There are two methods for providing static IP and hostname to a host:

Manual configuration

Works best for a single host but there is no central registration of hostnames and IP addresses - so there is an increased risk of IP address collisions

DHCP server provides fixed IP addresses based on the MAC address of the client

Works best if you need to manage many hosts (such as on a separate subnet). Requires adjustment of DHCP server configuration. Outrun has built-in DHCP services that work this way.

6.5 Validation questions

Answer these questions before configuring Outrun networking

DHCP server

Does the LAN have a DHCP server that provides valid IP address, netmask, gateway configuration?

DHCP hostname

Does the DHCP server provide a valid hostname?

DHCP nameserver

Does DHCP provide the IP address of a valid, reachable DNS nameserver?

DNS server

Does the LAN have a DNS server that provides correct forward/reverse DNS lookups for the hostname?

6.6 Network settings

The first thing you need to verify is the network settings. Note that as long as the IP and DNS settings are not setup correctly, the menu may respond a bit sluggish (due to DNS timeouts). This will be solved once the networking is set up correctly.

Main menu ⟹ Networking

6.7 DHCP and auto-configuration

Outrun is designed to make use of DHCP and auto config as much as possible. However, many networks don't offer DHCP services, others have DHCP that don't provide all networking details. In case where DHCP is not available or only provides limited IP settings, you need to configure some settings manually.

To find out what settings to use, answer the following questions with Yes or No for the LAN where your Outrun system is connected to:

• Valid DHCP server: Does the LAN have a DHCP server that provides valid IP address, netmask, gateway configuration?
• Valid DNS server: Does the LAN have a DNS server that provides correct forward/reverse DNS lookups for the hostname?
• DHCP provides DNS IP address: Does DHCP provide the IP address of a valid, reachable DNS nameserver?
• DHCP or DNS provides valid Hostname: Does the DHCP server or the DNS server provide a valid hostname?

The way to configure networking is as follows:

Networking
Valid DHCP server	Yes	No	Manual configuration
DHCP Client	ON	OFF	Networking ⟹ Set_IP
Valid DNS server	Yes	No	Manual configuration
DNS Spoof	OFF	ON	-
DHCP provides DNS IP address	Yes	No	Manual configuration
Auto DNS	ON	OFF	Networking ⟹ Set_DNS
DHCP or DNS provides Hostname	Yes	No	Manual configuration
Auto Hostname	ON	OFF	Networking ⟹ Set_Hostname

6.8 Advanced network settings

Additional (optional) configuration

Networking ⟹ Advanced ⟹ MTU

Sets MTU size (Jumbo Frames)

Networking ⟹ Advanced ⟹ NTP

Sets NTP server (gets correct time from the specified NTP server). Note that this can also be provided via a DHCP server (but most DHCP servers don't)

Networking ⟹ Advanced ⟹ Private

Enables second network interface with private IP settings from DNS (for Oracle RAC)

6.9 Restarting network

After making changes you need to restart the network stack:

Networking ⟹ Restart

Restarts network and applies configuration to running environment

6.10 Verifying network settings

Via the menu you can check network settings:

Networking ⟹ Status

Shows networking status

7 Updating the system

7.1 Updating overview

Outrun is 100% based on RPM packages that hold all sorts of scripts, config and other files. I frequently update packages to provide new functionality or improvements, or bugfixes.

Updated packages are published via a YUM repository on my website. The steps for updating are:

1. Make sure the update repository is enabled and configured to use the correct web address
2. Run the update process

7.2 Daily updates

Outrun by default runs a daily cronjob that updates any new packages from the Outrun repositories.

outrun-jobs lists the enabled jobs.

outrun-jobs disable outrunupdate disables this job in case you run into problems.

A more sophisticated method if you have problems with a single package, is using the YUM versionlock plugin.

Say you want to stick with an older version of a package (such as asmdisks):

yum downgrade asmdisks
yum versionlock asmdisks
yum versionlock list

7.3 Update instructions

If Internet access is available on the host, all you need to run is

outrun-update

and Outrun will update automatically. This command will only update packages from the Outrun repositories. It does not update the standard Linux packages.

Alternatively, run the update process manually:

yum clean all
yum update

This will update from all repositories where possible, not just the Outrun repos. It allows you to review what gets done before actually updating.

7.4 Using a proxy server for updates

If your system sits behind a firewall, check the Using a HTTP proxy page.

7.5 Update repository

Outrun configures the YUM update repository after installation to use the web server where Outrun is hosted (currently: Outrun YUM update repository)

If your system cannot access the internet (even via proxy), refer to Using a local repository for further update instructions.

8 Troubleshooting

8.1 Overview

If something goes wrong during the initial install process, you can restart any wizard script at any time. They will simply not do anything or fail without making changes. Check the scripts in /opt/outrun/bin to re-install.

If something goes wrong during postinstall which causes Outrun not to be installed completely, it will retry after each reboot until the package "outrun" gets installed.

8.2 Starting all over

If you can't get problems fixed, you can wipe the boot disk:

wipedisk -f /dev/sda

and start over completely.

If the wipedisk command is not available (usually when the entire postinstall phase failed):

dd if=/dev/zero of=/dev/sda bs=1M count=10

Replace /dev/sda with your bootdisk if different.

Be aware that these commands cause data loss! Make sure you enter the correct command!

8.3 Outrun log files

Log files of Outrun installation are found under /var/log/, filenames:

/var/log/postinstall.log # Logs the postinstall process
/var/log/postinstall.err # Logs postinstall errors. The size of this file should be zero.

8.4 Oracle installation log files

Log files of the Oracle install process are created under /tmp/ and /opt/tmp, but have a tendency to be removed before you get a chance to inspect. Also finding problems in those files is extremely difficult.

A workaround for sorting out install problems is to log in via an X session as “grid” for grid and ASM installation, and as “oracle” for Oracle binaries and database creation. This should only be needed for troubleshooting. A simple embedded VNC server is provided if you install the "lightvnc" package – you can then connect on the default VNC port 5900.

If you completely want to start over with the install then you can delete everything on the /opt/oracle directory, then also remove /etc/oraInst.loc, /etc/oracle and /etc/oratab. Then re-start the install process.

8.5 Various problems

Many issues are caused by changing hostnames, IP addresses, etc. To avoid problems make sure that in particular your hostname does not change after installing Oracle clusterware.

Internet (Google) provides procedures to re-configure grid and ASM when changing hostnames. This is beyond the scope of this installation guide. A menu option to do this might be provided in the future.

8.6 Post-install troubleshooting

You can login before the postinstall phase is complete. However, you cannot start the Oracle install process before it is finished. Also the complete environment has not been finalised.

The login message will show as follows:

Post-install has not completed - wait for it to finish before continuing... 

You may monitor postinstall progress with the command (i.e. for troubleshooting purposes): tail -f /var/log/postinstall.log

Or check for postinstall errors: tail /var/log/postinstall.err

(the postinstall.err file should be empty, zero byte size. If this file contains errors, something went wrong. The installation may proceed but later during Oracle install the pre-checks will refuse further installation, until you clear this file to acknowledge the problems. Better is to fix the issue and re-install linux).

If the postinstall phase did not complete, it will restart after reboot (an RPM package named outrun-bootstrap, which is installed during kickstart, before the first boot) takes care of this. You can check if this package has been correctly installed:

rpm -qi outrun-bootstrap
rpm -qvl outrun-bootstrap

The file /etc/init/bootstrap.conf kicks off postinstall after the system starts up normally. It will skip the process if the file /etc/outrun-release exists, which is one of the very last files that get installed from the last package (outrun-*.rpm) so if this file exists, the installation has finished.

If the bootstrap files did not get installed, the most likely reason is that copying the RPM package from install media failed. You should see these files in /opt/squash:

/opt/squash/outrun-bootstrap.rpm
/opt/squash/outrun-0.9-base.squashfs

If you installed from the ISO image, the following file should also be present:

/opt/squash/outrun-0.9-centos.squashfs

The bootstrap package provides several YUM package repositories. You can list them using yum repolist

The minimal repositories that you should see are:

outrun-base      Outrun 0.9 - Base
outrun-updates   Outrun 0.9 - Updates

and one of

outrun-linux     Outrun 0.9 - Linux install image
OR
outrun-centos    Outrun 0.9 - CentOS 6.6 subset

If you have installed via PXE booting, you might also see (depending on how PXE is configured):

outrun-local     Outrun 0.9 - Local
outrun-testing   Outrun 0.9 - Testing

The number of packages for outrun-base and outrun-linux/outrun-centos may not be zero or result in errors.

The Outrun base package set should be available via

/media/outrun/0.9/base

The Outrun CentOS subset (when installing via ISO) should be available via

/media/outrun/0.9/centos

If you installed via PXE server, then the local CentOS subset is not available and additional Linux packages get installed over the network via the PXE server. More details on the location of these packages can be retrieved via: yum repolist -v outrun-linux

Needless to say that if the PXE server refuses access to FTP and to the right YUM folders, the installation fails. After fixing the FTP server and rebooting the Outrun host, it should restart the process.