Merge pull request #17 from robert-w-gries/feature/oac-doc

Add OAC installation instructions

Author: chrisvanheuveln

docs/README-agent-install.md

@@ -31,15 +31,24 @@ Please note: A virtual Nexus N9000/N3000 may be helpful for development and test
 chef-client software.
 
 #### Environment
-NX-OS supports two possible environments for running 3rd party software:
-`bash-shell` and `guestshell`. Choose one environment for running the
-chef-client software. You may run chef-client from either environment but not both
-at the same time.
+NX-OS supports three possible environments for running third party software:
+`bash-shell`, `guestshell` and the `open agent container (OAC)`.
+
+|Environment                  | Supported Platforms                      |
+|-----------------------------|------------------------------------------|
+|`bash-shell` or `guestshell` | Cisco Nexus 30xx, 31xx, 93xx, 95xx, N9Kv |
+|`open agent container (OAC)` | Cisco Nexus 56xx, 60xx, 7xxx             |
+
+You may run chef-client from either `bash-shell` or `guestshell` on supported platforms but not from both at the same time.
 
 * `bash-shell`
    * This is the native WRL linux environment underlying NX-OS. It is disabled by default.
 * `guestshell`
    * This is a secure linux container environment running CentOS. It is enabled by default in most platforms.
+* `open agent container`
+   * This is a 32-bit CentOS-based container created specifically for running chef-client software.
+   * OAC containers are created for specific platforms and must be downloaded from Cisco.
+   * The OAC must be installed before the Chef client can be installed.
 
 #### Network Setup
 
@@ -192,11 +201,165 @@ EOF
 
 ```
 
+## <a name="env-gs">chef-client Environment: open agent container</a>
+
+This section is only necessary if chef-client will run from the `open agent container`.
+
+#### Set Up NX-OS
+
+Download the `OAC` `oac.1.1.0.ova` file.
+
+| Platform | OAC Download Link |
+|----------|-------------------|
+| Nexus 7xxx | [Nexus 7xxx Download Link](https://software.cisco.com/download/release.html?i=!y&mdfid=283748960&softwareid=282088129&release=7.3%280%29D1%281%29&os=)|
+| Nexus 56xx and 60xx | [**TODO**]|
+
+Copy the `ova` file to the `bootflash:` device.
+
+~~~
+n7k# dir bootflash: | inc oac.1.0.0.ova
+   45424640    Feb 12 19:37:40 2016  oac.1.0.0.ova
+~~~
+
+Use the `show virtual-service global` command to display available resources for the `OAC` Virtual Service.
+
+~~~
+n7k# show virtual-service global 
+...
+Resource virtualization limits:
+Name                        Quota    Committed    Available
+-----------------------------------------------------------------------
+system CPU (%)                  6            0            6
+memory (MB)                  2304            0         2304
+bootflash (MB)                600            0          600
+
+n7k# 
+~~~
+
+The recommended minimum values are currently:
+
+~~~bash
+  memory    : 256MB
+  bootflash : 400MB
+~~~
+
+**NOTE:** If insufficent `bootflash:` resources are available, remove unneeded files from `bootflash:` to free up space.
+
+Install the `OAC` Virtual Service using the `virtual-service install` command:
+`virtual-service install name oac package bootflash:oac.1.1.0.ova`
+
+~~~
+n7k# virtual-service install name oac package bootflash:oac.1.1.0.ova
+Note: Installing package 'bootflash:/oac.1.1.0.ova' for virtual service 'oac'. Once the install has finished, the VM may be activated. Use 'show virtual-service list' for progress.
+
+n7k# 2016 Feb 12 19:51:14 n7k %$ VDC-1 %$ %VMAN-2-INSTALL_STATE: Successfully installed virtual service 'oac'
+
+n7k# show virtual-service list
+
+Virtual Service List:
+
+Name                    Status             Package Name
+-----------------------------------------------------------------------
+oac                     Installed          oac.1.1.0.ova
+
+n7k# 
+~~~
+
+Activate the OAC using the `virtual-service` configuration command:
+
+~~~
+n7k# config t
+Enter configuration commands, one per line.  End with CNTL/Z.
+n7k(config)# virtual-service oac
+n7k(config-virt-serv)# activate
+Note: Activating virtual-service 'oac', this might take a few minutes. Use 'show virtual-service list' for progress.
+n7k(config-virt-serv)# 
+n7k(config-virt-serv)# end
+n7k# 
+n7k# 2016 Feb 12 19:55:06 n7k %$ VDC-1 %$ %VMAN-2-ACTIVATION_STATE: Successfully activated virtual service 'oac'
+~~~
+
+You may verify activation by using the `show virtual-service list` command:
+
+~~~
+n7k# show virtual-service list
+
+Virtual Service List:
+
+Name                    Status             Package Name
+-----------------------------------------------------------------------
+oac                     Activated          oac.1.1.0.ova
+
+n7k# 
+~~~
+
+Open a console session to the `OAC` using the `virtual-service connect` command:
+
+`virtual-service connect name oac console`
+
+*note: The OAC's root password is initially set to `oac`. You are required to change it on initial login.*
+
+~~~
+n7k# virtual-service connect name oac console
+Connecting to virtual-service.  Exit using ^c^c^c
+Trying 127.1.1.5...
+Connected to 127.1.1.5.
+Escape character is '^]'.
+
+
+CentOS release 6.7 (Final)
+Kernel 2.6.99.99 on an x86_64
+
+localhost login: root
+Password: 
+You are required to change your password immediately (root enforced)
+Changing password for root.
+(current) UNIX password: 
+New password: 
+Retype new password: 
+[root@localhost ~]# 
+~~~
+
+See [References](#references) for more OAC documentation *TODO*.
+
+#### Set Up OAC Network
+
+The `open agent container` is an independent CentOS container that doesn't inherit settings from NX-OS; thus it requires additional network configuration.  This configuration will be applied inside the `OAC` container.
+
+Connect to the OAC console, then:
+
+~~~bash
+
+# First become root:
+sudo su -
+
+# Enter the management namespace if your device uses the management interface for connectivity.
+chvrf management
+
+# Set up hostname and DNS configuration
+hostname n7k
+
+echo 'n7k' > /etc/hostname
+
+cat >> /etc/resolv.conf << EOF
+nameserver 10.0.0.202
+domain mycompany.com
+search mycompany.com
+EOF
+~~~
+
 ## <a name="agent-config">chef-client Installation, Configuration and Usage</a>
 
-This section is common to both `bash-shell` and `guestshell`.
+This section is common to `bash-shell`, `guestshell` and the `open agent container`.
+
+#### Install Chef-Client
+
+If needed, configure a proxy server to gain network access to `chef.io`:
 
-#### Chef Installation
+~~~bash
+export http_proxy="http://proxy.yourdomain.com:<port>"
+export https_proxy="https://proxy.yourdomain.com:<port>"
+~~~
 
 ##### Run Chef Install Script