The oo-install utility is designed to ease the experience of a trial or basic OpenShift installation by interactively gathering the data to run a simple deployment. The current iteration of oo-install enables the configuration and deployment of OpenShift according to the following scenarios:

  • Deploy all OpenShift components to one or more hosts

  • Add a new node host to an existing OpenShift deployment

oo-install is a deployment tool that has been optimized to simplify the process of getting a running OpenShift system on your chosen host systems. If you want to use OpenShift with an existing MongoDB database, ActiveMQ server, or DNS server, check out the Comprehensive Deployment Guide instead.

Do I Have To Read a Manual?

In short, no. One of the design goals of the oo-install utility is to make this document completely unnecessary. If you are feeling bold, you are heartily encouraged to attempt to use the installer right now without any additionaly guidance. Check out for the quick rundown on how to get started. If you run into problems, head back here or send your questions and feedback to the mailing lists or IRC channels mentioned on the oo-install web page.

Source Code

The locations for the source code of this document and the oo-install utility are as follows:

1. Before You Begin

This section covers some topics that will help you to have a successful OpenShift deployment. If you have jumped straight in with and are having problems, look over this section to make sure you’ve got the basics covered.

Note that it is not necessary to run oo-install on your target system(s) for the OpenShift installation. For instance, it is completely possible to run oo-install from your dekstop system against servers that you have provisioned in the cloud. Consequently the pre-requisities are split between the "installer host" requirements and the "target host" requirements.

1.1. Installer System Prerequisites

The list of utilities required by the installer is as follows:

  • curl

  • ruby (1.8.7 or greater)

  • ssh (if you are deploying OpenShift to systems other than the installer host)

  • tar

Most operating systems that provide a bash shell will include these utilities (with the possible exception of Ruby).

1.2. Target System Prerequisties

The follow sections describe the system requirements for a host that will be part of an OpenShift deployment.

1.2.1. Supported OSes

OpenShift Origin version 4 is supported on Red Hat Enterprise Linux (RHEL) 6.4 or higher and CentOS 6.4 or higher, 64 bit architecture only. This version is not supported on Fedora, RHEL 7.x or CentOS 7.x.

When you install Red Hat Enterprise Linux or CentOS, you will be given the option to select a starting set of packages:


Be sure to select the "Minimal" installation. This will ensure that the system does not contain any package incompatibilities with OpenShift.

There are no other utility prerequisites; oo-install will check for and offer to install the other utilities that it needs.

Deployment Mechanisms
For the curious, OpenShift Origin uses a Puppet module for deployments while OpenShift Enterprise uses a kickstart script. oo-install's job is to take your input and translate it into configuration files that drive these tools.

1.2.2. Remote Installation

If you are running the installer locally, but your OpenShift deployment will be installed on a remote system, you will need passwordless SSH access to your target host(s). "Passwordless" here means that either you are using an SSH key pair that was generated without a password, or that you are using a password manager like ssh-agent to provide the password as necessary.

2. Running the Installer

The oo-install utility has been developed to function as a standalone application. However, the easiest way to run it is by using a "curl-to-shell" command to download and execute the latest version of the installer in a single step. This section describes running the curl-to-shell command and also how to run the installer from the source code.


The recommended method for installing OpenShift is via a "curl-to-shell" command. From your command line, just run

$ sh <(curl -s

If you want to pass arguments to the installer, include them after the whole command:

$ sh <(curl -s -e -s rhsm -u

By default, the installer runs in Origin mode. If you want to install OpenShift Enterprise, you can either run:

$ sh <(curl -s -e


$ sh <(curl -s

OpenShift Enterprise installations require access to Red Hat Subscription Manager or Red Hat Network, and are verified to succeed on hosts running under a current Red Hat Enterprise Linux subscription.

2.2. Portable Installer

You can download a version of the online installer for use on a CD or USB drive. The latest versions of the portable packages are available at:

To use these portable installers:

  1. Download and unzip the portable installer zip file.

  2. Copy or burn the unzipped files to a USB drive or CD-ROM, respectively.

  3. Refer to the included README for instructions on starting the installation from the provided launcher.

Be aware that even if you are using the portable installer, your target hosts systems may still require internet access for necessary OpenShift RPMs.

2.3. Running oo-install from source

If you are working on oo-install development, you can also run the installer directly from source:

  1. Clone the openshift-extras repo from GitHub: git clone

  2. cd openshift-extras/oo-install

  3. bundle install (You only need to do this the first time)

  4. bundle exec bin/oo-install

Because oo-install is built to support remote deployments, you don’t need to set up a development environment on a target system in order to do this; you can clone the repo locally and run installations against remote systems directly from there.

2.4. Installer Command-Line Options

The complete list of options is as follows:

-a, --advanced-mode              Enable access to message server and db server customization.
-c, --config-file FILEPATH       The path to an alternate config file
-w, --workflow WORKFLOW_ID       The installer workflow for unattended deployment.
    --force                      Ignore workflow warnings and automatically install missing RPMs.
-l, --list-workflows             List the workflow IDs for use with unattended deployment.
-e, --enterprise-mode            Show OpenShift Enterprise options (ignored in unattended mode)
-s, --subscription-type TYPE     The software source for installation packages.
-u, --username USERNAME          Red Hat Login username
-p, --password PASSWORD          Red Hat Login password
    --use-existing-puppet        For Origin; do not attempt to install the Puppet module
-d, --debug                      Enable debugging messages

2.4.1. -a / --advanced-mode

By default, the installation utility will automatically install MongoDB and ActiveMQ on the same system that you designate as the OpenShift Broker. If you would prefer to install these services on different hosts systems, pass the -a flag and you will br prompted to provide information on these other target systems. For more on "deployment roles", see the Roles Summarized below.

2.4.2. -c / --config-file FILEPATH

The installer will look for a configuration file at the default location ~/.openshift/oo-install-cfg.yml. If you want to use a different file, you can pass the filepath with this option. If the file that you specify does not exist, it will automatically be created with some basic settings.

2.4.3. -w / --workflow WORKFLOW_ID

If you have already configured a complete OpenShift deployment, you can run the installer without any user interaction by providing this argument and the ID of an installer workflow. For example, you can run the OpenShift full deployment workflow like this:

$ sh <(curl -s -w origin_deploy

When you run the command this way, the installer will sanity check your deployment configuration, and if everything looks good it will run the specified workflow automatically.

When you are using the -w flag, you can also include the --force flag; this tells oo-install to automatically install required RPMs (like puppet for Origin deployments) without asking the user.

2.4.4. -l / --list-workflows

In order to use the -w option, you will need to see a list of the valid workflow IDs that are available. When you run the installer with this flag, it will print out the valid list of IDs and descriptions of each associated workflow.

The list of available workflow IDs will be different depending on if you are performing an OpenShift Origin installation or an OpenShift Enterprise installation. See the -e options for more on this.

2.4.5. -e / --enterprise-mode

In default mode, the installer will provide you with options for installing or extending an OpenShift Origin deployment. However, the same installer can be used to deploy OpenShift Enterprise by setting this switch.

2.4.6. -s / --subscription-type TYPE

Subscription refers to where your openshift component RPMs are coming from. oo-install supports four options:

  • none - If you have manually configured yum repos on the target hosts, and those repos already include the OpenShift RPMs, the none value tells the installer to use what you have already set up.

  • yum - Indicates that you would like the installer to create new yum repo entries for you under /etc/yum.repos.d/

  • rhsm - (For OpenShift Enterprise) Tells the installer that you want to use Red Hat Subscription Manager to set up OpenShift software channels

  • rhn - (For OpenShift Enterprise) Tells the installer that you want to use Red Hat Network to set up OpenShift software channels

The -s option exists to enable you to override the installer config file from the command line. This would typically be done in concert with the -w option as part of the setup for an unattended installation. For more information on subscriptions see Subscription, below.

2.4.7. -u / --username USERNAME

As indicated in the explanation of the -s option above, this option exists to enable you to override the installer config file from the command line. Currently, the -u setting is only meaningful in a scenario where you would be running an unattended installation (see -w) of OpenShift Enterprise (see -e) using the rhsm or rhn subscription methods.

2.4.8. -p / --password PASSWORD

See the comments on the -u option; this option would only be used under the same conditions.

2.4.9. -d / --debug

Enabling debug mode will cause the installer to periodically dump out large volumes of information about the SSH sessions that it attempts to establish as it runs. This can be useful for debugging remote deployments.

3. Configuring Your Deployment

When you run the installer for the first time, you will be asked to describe a number of items related to the OpenShift deployment that you want to set up. This whole process should be pretty self-explanatory, but here are some notes about the main facets of the configuration process.

3.1. DNS

When you use oo-install to deploy OpenShift, the installer offers to configure a BIND server to run on one of the same hosts where a Broker will run. The primary function of this BIND instance is to provide lookup information for applications that are created by the users of your OpenShift system, but it can also be configured to support a separate zone for the openshift hosts themselves.

3.1.1. Registering OpenShift Hosts with the OpenShift DNS Instance

Depending on your lab setup, you may already have a DNS solution in place for your host systems. If not, you can opt to register your OpenShift hosts with the Broker’s BIND server. This enables the hosts to look each other up by name in an environment where they may not be able to do name lookups otherwise.

When the installer asks you:

Do you want to register DNS entries for your OpenShift hosts with the same OpenShift DNS service that will be managing DNS records for the hosted applications?

…answering yes will notify the installer that you want this registration to be done. If you do answer yes, you will be asked a followup question:

What domain do you want to use for the OpenShift hosts?

While it is possible for you to answer this question with the same domain that you are using for OpenShift-hosted applications, it is recommended that you use a different domain.

For instance, if your domain is "", you might use:

  • for your OpenShift applications domain and

  • for your OpenShift hosts domain

3.1.2. Interacting with the OpenShift DNS Instance

After installation, the Broker-based DNS server can be used separately from a larger DNS infrastructure, or easily configured to work in concert with one. See the Appendix for more on this.

3.2. Host and Roles

After you have set the DNS configuration, you will be guided through the process of describing the hosts where OpenShift will be installed.

oo-install sees OpenShift deployments as a collection of hosts that have been assigned to certain roles. All of the roles can be assigned to a single host (an "all-in-one" deployment), or they can be distributed to different hosts. Furthermore, all of the roles can be assigned to more than one host to configure a High Availability deployment. See the High Availability Deployments topic for more on this.

3.2.1. Roles Summarized

There are four roles that a host can perform in an OpenShift deployment: Broker, DBServer, MsgServer and Node.


The Broker role consists of the OpenShift Broker RPMs and an MCollective client. The Broker serves as a central hub of the OpenShift deployment, and provides a web interface where users can manage their hosted applications.


This role consists of the MongoDB database that the Broker uses to track users and applications.


The MsgServer role comprises the ActiveMQ server plus an MCollective client.


The Node role is assigned to any host that will actually be used to store and serve OpenShift-hosted applications. oo-install supports the deployment of Nodes as part of an initial installation and as part of a workflow to add a new Node to an existing OpenShift deployment.

3.2.2. OpenShift Hosts

The installer guides you through the process of gathering the following information about each host that you are going to use in your deployment.

Host Name

This should be pretty self-explanatory. The installer is looking for the fully qualified domain name (FQDN) of the host. If you provided an OpenShift hosts domain during DNS configuration, you can get away with typing just the hostname here and the installer will append the rest for you.

Why can’t I use localhost here?
If you only ever wanted to deploy an all-in-one OpenShift system, you could use localhost in all of the OpenShift configuration files. However, adding Nodes to an all-in-one deployment would require the revision of all of the configuration files to use the Broker’s FQDN. Consequently the installer prevents the assignment of localhost as the hostname value for any OpenShift host.

SSH Host Name

If the host in question is not the host where you are running the installer, this field enables you to specify the name of the SSH target for remote installation. This value can be:

  • An IP address

  • A DNS name that already resolves to the host

  • Identical to the Host Name

  • An alias from your ~/.ssh/config file

  • localhost

When you set the value of the SSH Host Name to localhost, you are telling the installer that you are running oo-install on the host that you are currently describing. In this case, oo-install will not use SSH to interact with this host instance, but will attempt to run the commands locally. Otherwise, oo-install will use this value in conjunction with the User value to start SSH sessions with this host.


When the host that you are currently describing is a remote system, this value is used in conjunction with the SSH Host Name to establish SSH sessions with the target host. If you are running the installer on the target host itself (in other words, if you are using SSH Host Name localhost for this host instance), then you will not be asked this question; the installation will run with whatever privileges your user account has.

In either case, the user in question must satisfy one of these two requirements:

Under RHEL, passwordless sudo configuration may not succeeed unless you set the following in your /etc/sudoers file for your target user:

Defaults:<username>    !requiretty

Try setting this if you see error messages like:

sudo: sorry, you must have a tty to run sudo
IP Address

At this point, the installer will attempt to look up the IP addresses that have been assigned to the host that you are currently describing. In a situation where the host has multiple NICs, there may be multiple IP addresses to choose from.

Non-Node Hosts
The IP address that is provided here should be the one that would be used by other OpenShift hosts would use to connect with this host.

Node Hosts
In the case of Node hosts, you will want to use the IP address that client systems would use to reach the host.

Manual Entry
You also have the option of supplying a completely different IP address. This may be necessary in situations where one OpenShift host is separated from the others in a NAT environment.

IP Address and DNS Registration
If you have told the installer to register your OpenShift host names with the OpenShift DNS instance, this IP address will be used as the resolution of this hostname.

IP Interface

This value is only collected for Node hosts in OpenShift Origin deployments. This is a requirement of the underlying Puppet infrastructure. If you select one of the IP address / IP interface combos that oo-install finds on the host, you will not need to provide this at all. On the other hand, if you manually configure the IP address, you will also need to manually specify the interface. To see the available IP interfaces on a given host, you can run this command:

$ ip link show

Which will yield output like this:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: em1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT qlen 1000
    link/ether f0:de:f1:de:88:0f brd ff:ff:ff:ff:ff:ff
3: wlp3s0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT qlen 1000
    link/ether 24:77:03:64:a9:28 brd ff:ff:ff:ff:ff:ff

Or you can run:

$ ip addr list

Which will additionally provide each interfaces current IP address assignment (if applicable):

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host
       valid_lft forever preferred_lft forever
2: em1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000
    link/ether f0:f0:f0:f0:f0:f0 brd ff:ff:ff:ff:ff:ff
    inet brd scope global em1
       valid_lft forever preferred_lft forever
    inet6 1111:11:1:1111:1111:1111:1111:1111/64 scope global dynamic
       valid_lft 2591966sec preferred_lft 26sec
    inet6 1111::1111:1111:1111:1111/64 scope link
       valid_lft forever preferred_lft forever
3: wlp3s0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN qlen 1000
    link/ether f1:f1:f1:f1:f1:f1 brd ff:ff:ff:ff:ff:ff
Service Accounts

Finally, all hosts get configured with service account information. Unlike other settings that are unique to each host, oo-install ensures that the service account parameters are identical across the deployment. The following items comprise the service account settings and their default values:

  • mcollective_user: mcollective

  • mcollective_password: (randomly generated)

  • mongodb_broker_user: openshift

  • mongodb_broker_password: (randomly generated)

  • mongodb_admin_user: admin

  • mongodb_admin_password: (randomly generated)

  • openshift_user: demo

  • openshift_password: (randomly generated)

Any time you modify a host in your deployment, oo-install gives you an opportunity to revisit these values. Note however that once you have done an initial deployment, oo-install is not capable of changing the values.

3.2.3. Basic and Advanced Role Deployment

By default, the installer runs in basic mode. In basic mode, the installer automatically assigns the DBServer and MsgServer roles to the same host where the Broker is assigned. If you need more flexibility, you can override basic mode by passing the -a argument to the installer command.

Moving Roles Between Hosts
Up until the point where you actually deploy the OpenShift configuration that you are describing, you will have the opportunity to move roles between the host instances that you have defined. In basic mode, moving a Broker role implicitly moves a DBServer and MsgServer role, as well.

3.3. High Availability Deployments

For low-volume and Proof-of-Concept Origin deployments, you can deploy OpenShift with a single Broker, DBServer and MsgServer role. However, oo-install also supports thedeployment and configuration of High Availibility options for each of these roles. During your deployment configuration, if you specify more than one host as a Broker, DBServer or MsgServer, oo-install will automatically configure the additional services and settings necessary for high availability.

Best Practices: The Rule of Three
While oo-install will allow you to deploy HA services with any number of members, the most predictable results are had with three instances of the Broker, DBServer and MsgServer roles. An openshift deployment that uses three of each of these roles can scale to a very large number of supported Nodes and a significantly larger number of applications while adding a powerful but manageable amount of fault-tolerance.

3.3.1. HA Brokers

When you use oo-install to deploy OpenShift Enterprise, it is up to you to decide how to coordinate the Brokers to act as a highly available cluster. OpenShift Origin deployments solve this by deploying and configuring a simple web proxy to dynamically dispatch Broker requests to one of your Brokers.

Web Proxy Configuration (Origin Only)

You will be asked to provide a virtual Broker hostname and virtual Broker IP address to use. These values are used by an HAProxy server that is installed on the Broker host of your choice. If you are also using OpenShift’s DNS to do name resolution for your host systems, this virtual name / IP combination will be added to that configuration as well.

Picking a Virtual IP Address That Will Work
If you are just experimenting with high-availability Brokers, then the easiest way to ensure that your Broker virtual IP address is going to work is to make sure that it is part of the same subnet as the rest of your OpenShift hosts. Adding custom IP routes to handle a virtual IP address that is not part of the same subnet is outside of the scope of this document.

Coordinating Authentication

Installations that are deployed with oo-install use basic HTTP-based authentication, which is driven by the /etc/openshift/htpasswd file on the Broker host system. If you are deploying multiple Brokers, you will either need to ensure that all Broker htpasswd files are kept in sync, or you may want to switch to a different authentication option after the installation is done. If you want a different authentication method from the outset, consider using the OpenShift Origin Puppet module directly.

3.3.2. HA DBServers

OpenShift uses MongoDB to manage user and host application information. MongoDB has native replica set support, which oo-install can configure for you. When you declare more than one DBServer system in an OpenShift deployment, the installer will ask you to choose which host will be the primary, and the rest of the work is done for you.

3.3.3. HA MsgServers

OpenShift uses ActiveMQ to handle inter-host messaging, and ActiveMQ has native support for failover clustering. This doesn’t require any special configuration input from user. If you specify more than one MsgServer host, failover clustering is automatically instantiated.

3.4. Gear Sizes

The installer will ask about three settings related to gear sizes. If you are not familiar with this concept, refer to the User Resource Management section of the Administrators Guide.

The installer configures these settings with the indicated defaults:

  • valid_gear_sizes - specifies all gear sizes that the current OpenShift Origin installation supports: "small,medium,large"

  • user_default_gear_sizes - specifies the sizes of gears available to all users upon user creation: "small,medium"

  • default_gear_size - specifies the size of gear that a new hosted app will get by default: "small"

The actual specifics about what each "gear size" means can be adjusted after installation is completed.

3.5. Node Districts

The installer also gathers information about the Node Districts that you would like to deploy. As of Origin version 4, it is no longer possible to deploy a Node host without associating it with a Node District. By default, the install will create a single Node District called "Default" that is associated with the "small" gear size.

3.6. Subscription

At this point, all that remains to configure your OpenShift deployment is to tell oo-install where you would like to get your OpenShift RPMs from. Refer to the notes on the -s / --subscription-type command-line argument for an explanation of your options.

The installer supports three different ways to set subscription preferences. This is great from a deployment flexibility perspective, but may be really confusing if this is your first time through an OpenShift deployment.

3.6.1. Pathway #1 - Command Line Options

The first way to set subscription preferences is via the command line. This option works well if you are building an unattended installation system and you want to dyanamically set this information. The settings provided at the command line will trump any conflicting settings from the installer config file. But if you are not running an unattended installation, you’ll still have the opportunity to override these values. Bottom line: don’t set subscription information on the command line unless you are using it in conjunction with an unattended installation (see the -w command line argument for more information).

3.6.2. Pathway #2 - Configuration File Options

Most commonly, you will just want to store subscription information in the installer config file. The main advantage to this is that you can reuse the subscription settings every time you configure a deployment. The main disadvantage to this is that you could potentially end up storing a piece of sensitive information (your RHSM or RHN password) to a cleartext file. In these situations, you will want to use a combination of this pathway and pathway #3; read on for more info.

Information that is stored in the oo-install configuration file is not encrypted. If you are using a subscription method that requires a user name and password, it is recommended that you omit the password from the configuration file. To do this, enter '-' as your password when the installer asks.

3.6.3. Pathway #3 - Runtime Options

After the installer gives you the opportunity to work with subscription settings in your configuration file, you will have the opportunity to set one-time values that are not stored in the configuration file. These values will be used during the current deployment and then forgotten by oo-install. This is suitable in particular for passwords that you do not want to capture in the non-encrypted installer config file.

3.6.4. Subscription Notes for OpenShift Origin

The most common subscription method for Origin is yum, and the current known good repos to use are these:

These values are provided by default in the configuration file that ships with the installer.

4. Pre-flight Checking and Installation

Once you’ve configured DNS, Hosts and Roles, and Subscription information, the installer will do a sanity check of the entire deployment. Specifically, for each host that you’ve described, the installer checks the following:

  • Is the host reachable? (see SSH Host Name)

  • Does the user have the necessary privileges? (see User)

  • Is the host’s system type supported by the installer?

  • Does the host have the necessary utilities installed for the selected installation task? (see Utility Prerequisites)

The installer will offer to install missing packages that are required for deployment. Most notably for OpenShift Origin, the installer will offer to install Puppet if puppet is not found on the target system(s).

4.1. Failing Pre-Flight?

If your deployment fails pre-flight, don’t panic. Have a look at what the error messages are telling you about missing utilities and SSH connection issues (these are the largest causes of preflight failure).

It is completely safe to rerun the installer if it fails preflight, and if you are totally stumped, get in touch with us so that we can help!

4.2. Installing (Grab Some Tea)

Once the pre-flight inspection is complete, the installer hands control of the installation off to a 'workflow executable'. The workflow executable’s job is to transform the configuration that you’ve described into instructions for deploying your OpenShift. The entire installation process can take anywhere from 10 to 45 minutes. During the process, you will see a fairly constant stream of information scrolling by in your command terminal. Additionally, once the installation work begins on each host, you can watch the progress from their perspective by tailing the installer log file:

$ tail -f /tmp/openshift-deploy.log

5. Post-Install Tasks

After the OpenShift installation is complete, the installer will attempt to perform several necessary post-install tasks for you:

  1. Restarting services in the necessary order for inter-host communication

  2. If appropriate, preforming the MongoDB replica set configuration on your speficied master DBServer

  3. Configuring the Node District(s) that you sepcified

  4. Registering the supported cartridges with your Broker(s)

If the installer encounters any failures at this point, they are most likely due to race conditions between services on separate hosts. In these cases the installer will instruct you about what post-install steps remain.

Rebooting OpenShift hosts is no longer necessary as a post-install action. oo-install has been improved to handle service restarts in a dependency-based order.

6. Using and Administering Your New OpenShift System

Once your system is up and running, your work with oo-install is complete. You cannot use oo-install to reconfigure your deployment, though you can use it to add Node hosts to your deployment.

From here, you can learn more about the management and operation of OpenShift from the following guides:

And don’t be afraid to reach out to the community for more help!

7. Appendix: Tying in OpenShift DNS with upstream DNS

7.1. Temporary DNS Integration

These instructions will enable you to set up temporary DNS integration on a Linux system. You can use this information as a guideline for accomplishing similar results on client systems running other operating systems.

On a client-by-client basis, you can do the following to work against the OpenShift DNS server:

  1. On the client system, make a backup copy of /etc/resolv.conf

    $ cp /etc/resolv.conf /etc/resolv.conf.bak
  2. Open the file with a text editor

    $ vi /etc/resolv.conf
  3. In the editor you will see something similar to this:

    • Modify the domain and search values to match the app domain (and optionally also the OpenShift host domain) that you specified.

    • After the search line, insert a new nameserver entry to point to the Broker host’s IP address.

    • Leave the other nameserver entries alone.

  4. No restart necessary; you should be able to point a web browser on this client system at the URL off an application in the app domain. If you’ve also registered the OpenShift hosts with OpenShift DNS, they should be reachable by name as well.

  • Once modified to use the Broker DNS, your client system will not be able to resolve non-OpenShift-registered hostnames until it is reverted to its original settings.

  • On a reboot, the client machine may overwrite your changes to the /etc/resolv.conf file

7.2. Permanent DNS Integration

For a more permanent solution, here’s how to delegate the OpenShift application domain (and if applicable, host domain) from your main DNS service to the OpenShift DNS server. The gist of the work is that you will be telling your main DNS service to delegate to the OpenShift DNS service based on the domain of the name to be looked up.

Keep in mind that DNS could be set up in one of a dozen different ways in your organization, so the best we can do is offer guidelines for what you are going to need to do.

DNS services can be thought of as domain containerships. The DNS service that provides lookup information for may also contain records for hosts in the subdomain Alternately it may delegate the job of subdomain lookups to another server. Delegation is how you will set the OpenShift DNS service to provide the lookup information for the OpenShift-hosted applications, and possibly also the information for the OpenShift hosts.

7.2.1. Step 1. Identify the Point of Delegation

First, you will need to determine the right DNS server or service layer where the delegation should be done. In a simple lab environment this may be pretty obvious, but in a large company this will probably involve the assistance of different members of your IT organization. Unfortunately, this guide can’t offer a lot of guidance there. The point is that whatever nameserver is the authority for the nearest containing subdomain, that’s generally the one where you’ll want to define the NS records that refer to your OpenShift nameserver for its domain(s).

7.2.2. Step 2. NS Records and A Records

Once you’ve identified where delegation should occur, you will need to configure the delegation itself. For a typical example, let’s say you own, and you want to delegate to your OpenShift BIND server:

  • The root nameservers delegate "com" to the .com nameservers.

  • The .com nameservers delegate "" to your nameservers.

  • On your nameserver, you would define a record for the nameserver:   NS

    And then you would define that name with an IP that points to your OpenShift DNS server:  A  10.x.x.x

The exact method/syntax for defining will vary by nameserver type, but the outcome should look the same when verified with dig.

Between you and us, we don’t know why you couldn’t just put the IP in the NS record and have done, but no one seems to do it that way. Levels of indirection and caching, perhaps?

The OpenShift nameserver can then go on to define subdomains, for instance and, as it is the master of this (sub)domain.