Using NIM for installing AIX updates and new packages over the HTTP protocol

Edit online

Network Installation Manager (NIM) supports the installation of AIX® updates over the Hypertext Transfer Protocol Secure (HTTP) protocol to conform to the emerging data center policies that restrict the use of network file server (NFS).

AIX BOS installation still requires the use of the NFS version 3 protocol or the more secure NFS version 4 protocol. In addition to the installation of filesets, NIM customization processes such as script execution and copying the file_res directory are supported over the HTTP protocol.

The HTTP protocol provides the following advantages for NIM management:

All communication occur over a single HTTP port. Hence, the authorization through a firewall is easier to manage.
AIX installation steps are driven from the client's end, that is, the target system of the installation. Therefore remote access is not required for running the commands.
NIM or any other products that currently use the client-server model of NFS can easily use HTTP.
Able to extend the end product to support additional protocols.

NIM HTTP Service

AIX 7.2.0 ships a new service handler that provides HTTP access to NIM resources. The nimhttp service is defined in the /etc/services and the nimhttp daemon, which listen for requests over the 4901 port. When the nimhttp service is active, NIM clients attempt to access the /etc/services file and request customization of the scripts that are defined in the nimhttp service. If HTTP access fails or if the access is denied, access failover attempt to the NFS client occurs.

Enabling the nimhttp service on the NIM server

To enable the nimhttp service, run the following command on the NIM server:

# nimconfig -h

Note: The crypto or ssl setting is automatically discovered.

When the nimhttp service is started, the service attempts to read the httpd.conf configuration file that is located in the default home directory of the root user. If you are using the nimhttp service for the first time, and if you start the nimhttp service without creating a configuration file, a configuration file is created and populated with default values of the nimhttp service.

An example of the default httpd.conf configuration file follows:

# cat /httpd.conf
#
#
#http service defines
#
#
service.name=nimhttp
# Designates the service name used  when discovering the listening port for requests (i.e., nimhttp)
#
service.log=/var/adm/ras/nimhttp.log
#Log of access attempts and equivalent responses. Also useful for debug purposes.
#
# service.proxy_port=
#Designates the service portnumber used when configured as a proxy.
#
#---------------------------------------------------------------
#	http configuration 
#---------------------------------------------------------------
#	
document_root=/export/nim/
#Designates the directory to serve files from.
#	
enable_directory_listing=yes
#Allow requests for listing served files/directories under the document root.
#
enable_proxy=no
#Enable the webservice to act as a proxy server.
#
ssl.cert_authority=/ssl_nimsh/certs/root.pem
#Designates the file location of the certificate authority used for digital certificate signing.
#
ssl.pemfile=/ssl_nimsh/certs/server.pem
#Designates the file location of the PEM format file which contains both a certificate and private key.
#

The properties of the httpd.conf file

The httpd.conf file has the following properties and settings:

document_root path

Files that are not defined as resource locations can be accessed by using the HTTP protocol. These files must be located in the path setting of the document_root. The defined document_root path location cannot be modified when the nimhttp service is operational.

The document_root path might contain many directories. When you set the enable_directory_listing option, client requests can travel the document_root path. If the enable_directory_listing option is set to value of no, all files that are used during the installation must be located in the current working directory of the document_root path.

Secure Socket Layer (SSL) settings

The nimhttp service uses basic protocol handshake as the default authentication. You must provide valid paths for the certificate authority (CA) and the root certificate files for the server to enable a more secure Digest Authentication method.

The certificate authority and root Privacy Enhanced Mail (PEM) files used in the nimhttp service can be created by using the existing SSL management option in NIM. To create the ssl.cert_authority and ssl.pemfiles files that are used by the nimhttp service, run the following command on the NIM master:

# nimconfig –c

Note: You do not need to create the ssl.cert_authority and ssl.pemfiles files if these SSL files exist in the current directory.

To check whether the NIM master has been configured for SSL authority before starting the nimhttp service by using the SSL option, run the following command on the NIM master:

# lsnim –a ssl_support

Proxy settings

The NIM client commands depend on the nimhttp service because the NIM server acts as the file server that hosts the NIM resources.

Alternatively you can use the proxy option for handling an HTTP request by using the nimhttp server code. When the proxy option is enabled by using the value enable_proxy=yes, any requests for service over the nimhttp port are forwarded to the service port listed in the service.proxy_port list of ports.

The HTTP authentication is handled by the destination service and not by the nimhttp service. The destination service port is identified locally in the NIM client.

Disabling the nimhttp service on the NIM server

To disable the nimhttp service, run the following command on the NIM server:

# nimconfig -H

NIM resources that support HTTP access

The following resources can access the http file by using the nimhttp service:

file_res
fix_bundle
installp_bundle
lpp_source
script

Examples

To install the bos.sysmgt.nim.master fileset and to define basic resources, run the following command:
```
# nim_master_setup –a device=/dev/cd0
```
To enable Secure Socket Layer (SSL) management for the NIM environment, run the following command:
```
# nimconfig –c
```
To enable the nimhttp service with SSL support, run the following command:
```
# nimconfig -h
```
To check the service log file for any errors that have occurred, run the following command:
```
# cat /var/adm/ras/nimhttp.log
```

If you are using the push operation, the following commands support the nimhttp service:

nim –o cust–a file_res= <obj_name> <client_obj_name>
nim –o cust–a script= <obj_name> <client_obj_name>
nim –o cust –a lpp_source=<obj_name> -a filesets=<fileset names to install> 
                                                <client_obj_name>
nim –o cust –a lpp_source=<obj_name> -a installp_bundle=<obj_name> <client_obj_name>
nim –o cust –a lpp_source=<obj_name> -a fixes=update_all <client_obj_name>

If you are using the pull operation from the NIM client, the following commands support the nimhttp service:

nimclient –o cust –a file_res=<obj_name>
nimclient –o cust –a script=<obj_name>
nimclient –o cust –a lpp_source=<obj_name> ---a filesets=<fileset names to install> 
nimclient –o cust –a lpp_source=<obj_name> ---a installp_bundle=<obj_name>
nimclient –o cust –a lpp_source=<obj_name> ---a fixes=update_all

Debugging session for the nimhttp service

The communication from the NIM master to the client occurs over the nimsh protocol, to run an application. But, the client requests the file resources be sent over the HTTP protocol instead of the usual NFS export or mount process. The following steps show an example debug session.

To start the nimhttp service from the NIM master, run the following command:
```
nimconfig -h
```
To keep the current window active from the NIM master for viewing the HTTP requests from the client, run the following command.
```
tail -f /var/adm/ras/nimhttp.log
```
In a separate window, either on the client or master system, run the cust operation that you want from a system on which AIX 7.2 is installed.
The log activity for the nimhttp service is displayed on the terminal window.

Confirming the use of HTTP instead of NFS

To ensure that the NIM cust operations are performed by using the HTTP protocol and not by using the NFS protocol, ensure that the NFS cannot access the NIM resources by removing entries from the /etc/exports file. For instructions, see steps 1 - 4 in the Debugging session for the nimhttp service section. After the NIM cust operation starts downloading filesets, run the exportfs -uav command to ensure that the NIM master does not failover to an NFS mount from the client.

If a nimhttp service request is received successfully, a log entry similar to the following example is displayed:

------
Mon Oct 26 14:45:37 2015	
nim_http: data string passed to get_http_request: "GET /client.defs HTTP/1.1

Connection: close

"

Mon Oct 26 14:45:37 2015	Request Type is GET
Mon Oct 26 14:45:37 2015	Sending Response Header "200 OK"

Mon Oct 26 14:45:37 2015	Sending file over socket 5. Expected length is 2989
Mon Oct 26 14:45:37 2015	Total length sent is 2989

Mon Oct 26 14:45:37 2015	handle_httpGET: Entering cleanup statement

Verifying the NIM environment configuration

You can use the following steps to confirm whether the NIM environment is configured properly for handling nimhttp services.

To verify whether the NIM master is listening for connection requests over a specific host address, run the following command on the NIM master:
```
# cat /etc/niminfo

# nimconfig -h	(if necessary)
 
# netstat -a | grep nimhttp
# netstat -i
# cat /httpd.conf
# cat /var/adm/ras/nimhttp.log
```
On the client, run the commands:
```
# cd /tmp
# nimhttp -f /export/nim -o dest=/tmp -v
```
To determine whether the client request has reached the NIM master, run the following command on the NIM master:
```
# cat /var/adm/ras/nimhttp.log
```
If the commands in step 1 result in an unexpected output, the client might be requesting the nimhttp service from a host IP on which the NIM master does not respond. You can check the list of the host name and IP addresses on which the master system is running. You can provide the host name as an argument to the nimhttp command that is provided during the previous client request. You can run the nimhttp -? command to understand the flag syntax of the nimhttp command.