NIM - BASICS

Basics

Master (NIM master):

The one and only one machine in a NIM environment that has permission to run commands remotely on NIM clients. The NIM master holds all the NIM resources. A client can only have one master, and a master can not be a client of any other master. The NIM master must be at an equal or higher level than the client.

Client (NIM client):
Any standalone machine or lpar in a NIM environment other than the NIM master. Clients use resources that reside on the NIM master to perform various software maintenance, backup ...

Resource (NIM resources):
This can be a single file or a whole filesystem that is used to provide some sort of information to, or perform an operation on a NIM client. Resources are allocated to NIM clients using NFS and can be allocated to multiple clients at the same time. Resources can be: mksysb, spot, lpp_source, machines...

Allocate/Allocation:
This process is what allows your NIM client to access resources in NIM. The master uses NFS to perform the allocation process. Resource can be allocated to one or more NIM clients at the same time. You can check which resources are allocated to clients by lsnim -a <type> command. For clean up purposes, the allocated resorces must be deallocated.

nimsh (NIM service handler):
For environments where the standard rsh protocols are not secure enough, nimsh may be implemented. With nimsh, the primary port is 3901, and it listens for service requests. The primary port is used for stdin and stdout while stderr is redirected to secondary, which is port 3902.

more info: http://www-01.ibm.com/support/docview.wss?uid=isg3T1010383

------------------------------------

NIM DATABASE:

The NIM database is stored in the AIX Object Data Management (ODM) repository on the NIM master and is divided into four classes: machines, networks, resources, groups.

    machines: shows the machines in NIM (master, clients)
    networks: shows what type of network (topology: ent, Token-Ring... ) can be used
    resources: shows resource types: mksysb, spot ...

------------------------------------

/ETC/NIMINFO:

This file always exist on the NIM master and mostly will exist on a NIM client. This file is a text file and contains hostname information for the client, tells the client who its master is, communication port and protocol informations. This file should not be edited manually. If there is incorrect information in the file, it should be removed and recreated.

rebuild /etc/nimifo of NIM master:
on NIM master: nimconfig -r

rebuild /etc/niminfo of NIM client:
on NIM master: smitty nim -> perf. nim adm. -> manage machines -> specify new master
(select client, then NIM master (if already used master name is used, it rebuilds /etc/niminfo on client))

on NIM client: niminit -a master=<MASTER_HOSTNAME> -a name=<CLIENT_NIM_NAME>
(niminit -a master=aixnim01 -a name=aix01 -a connect=nimsh (it will use nimsh, deafult is rsh))
(niminit -av name=aix31 -a master=aixnim1.domain.com -a master_port=1058 (-v: verbose mode))

------------------------------------

Commands on Master:

/var/adm/ras                       this directory contains the NIM master log files
/var/adm/ras/nimsh.log             log of nimsh (connection problem with client can be checked here)
/var/adm/ras/nimlog                general nimlog file, can be view: alog -f /var/adm/ras/nimlog -o (shows failed NIM operations)

lsnim                              shows the classes of the NIM database: machines, networks ... (it is stored in the ODM)
lsnim -c machines                  lists this class elements: machines, networks, resources
lsnim -t <type>                    lists the resources of that type (spot, lpp_source, mksysb, standalone...) (e.g. lsnim -t spot)
lsnim -l <resource>                shows the attributes of the resource (e.g. lsnim -l spot_5300_09)
lsnim -O <resource>                shows valid nim operations for that resource (remove, change...)(e.g: lsnim -O lpp5300)

nim -o check <resource>            check the status of a resource (nim -Fo check <rewsource>)
                                   (on lppsource: it will create .toc and checks filesets for simages attribute)
                                   (on spot: rebuilds the spot network boot images, if necessary, and change state to "ready for use")
                                   (on machine: check the status, if Cstate is not OK, it will inform about that)
nim -o lslpp <client>              lists client installed filesets (good command for checking connection between master and client)

lsnim -a spot                      shows which spot is allocated to which client (you can check lpp_source ans mksysb as well)
nim -o deallocate -a spot=<spot> <client>    it will deallocate the specified spot from a given client
nim -Fo deallocate -a subclass=all <client>  it will deallocate all allocated resources from a given client
                                   (-F is force, typically you should only need to use this flag with "reset" operation.)

nim -Fo reset <resource>           reset a NIM object state to "ready for NIM operation" (it is needed if an operation failed/stopped)
                                   (on machine: Cstate will be: ready for a NIM operation)
                                   (on spot: Rstate will be: ready for use)

nim -o remove <resource>           removes an object (object definitions will be removed from NIM db, but dir and filesets will remain)
                                   (if you remove a spot, directory will be removed as well (unless you umount it before the command)

nim -o change -a if2='' -a cable_type2='' master  it will remove if2, 2x single quotes (' ') are used , not a double quote (")

                                                  after that lsnim -l master | grep if will not show if2

------------------------------------

Commands on Client:

nimclient -l -L aix31                              list all available resources for the client (aix31)
nimclient -o allocate -a lpp_source=lpp5305        allocate an lppsource to the client
nimclient -o deallocate -a lpp_source=lpp5305      deallocate an lppsource to the client
nimclient -l -c resources aix31                    show allocated resources for the client
nimclient -Fo reset                                resetting the NIM client state

------------------------------------

How to reset/deallocate resources:
If resources were allocated to a client and later the operation failed or want to do a clean up:

1. check what is allocated:
    -lsnim -a spot, lsnim -a lpp_source, lsnim -a mksysb <--it will show which resource is alloated to which clients
    -lsnim -l <resource> | grep alloc_count              <--it will show how many clients it is allocated to
    -lsnim -l <resource> | grep state                    <--it will show Rstate/Cstate (Resource/Current state) of a resource
    -showmount -e; tail /etc/bootptab                    <--it not show if anything is exported to a client

2. reset the client state: (it will reset the Cstate/Rstate of a resource to "ready for use")
    -nim -Fo reset <client>
       
3. deallocate the given resources:
    -nim -o deallocate -a spot=<spot> <client>
    (nim -Fo deallocate -a subclass=all <client>)

------------------------------------

Preparing a system for maintenance (network) boot:

# nim -Fo reset <client>                              <--reset the state of the client (if it was not "ready for NIM operations")
# nim -o deallocate -a subclass=all <client>          <--deallocates all resources from client (if lpp_source/spot was allocated to it before)
# nim -o maint_boot -a spot=spot_5300-11-04 <client>  <--prepares the system for network boot

(after boot if needed later, you can do reset and deallocate again)

------------------------------------


SOME CHECKS FOR COMMON PROBLEMS:

ON MASTER:
- check the communication between nim master and client: nim -o lslpp <nim client>
- check if there are allocations to the client: lsnim -a spot ... (reset client, deallocate resource)


ON CLIENT:
- if rsh is used:
    -check correct connection (for connecttion refused error: inetd.conf, .rhosts file)
    -check if firewall is blocking communication (telnet to rsh ports)

- if nimsh is used:
    -check nimsh log: /var/adm/ras/nimsh.log
    -check if nimsh is running: lssrc -s nimsh (restart can help: stopsrc -s nimsh; startsrc -s nimsh)   
    -check /etc/niminfo file (if there is invalid entry, correct on master and recreate /etc/niminfo)


- for authentication (cpuid) problems in the log:
    on client check cpuid: uname -m
    on master compare it with stored value of the client: lsnim -l <client>
    if differs, change it to correct value (smitty nim --> perform nim adm. -> manage machines -> change show char.)
    or you can turn off cpu validation on master: nim -o change -a validate_cpuid=no master (/etc/niminfo on client my need to be recreated)
    (if validate_cpu is on yes, lsnim -l master will not show its value only if it is on no)

- for authentication errors in the log:
    may be problem with reverse reolution: in /etc/niminfo there is only a hostname, but /etc/hosts give back an FQDN:
    # grep NIMSH_AUTH /etc/niminfo
    export NIMSH_AUTH="master01|FF00FF00FF00"

    # host 192.168.1.1
    master01.domain.com is 192.168.1.1

    Change /etc/niminfo to include the domain and restart:
    # grep NIMSH_AUTH /etc/niminfo
    export NIMSH_AUTH="master01.domain.com|FF00FF00FF00"

    # stopsrc -s nimsh; startsrc -s nimsh

------------------------------------

on nimclient in /var/adm/ras/nimsh.log:
error: remote value passed, '00080EC2D550', does not match environment value '00080E82D990

This means, NIM client does not store in /etc/niminfo file the correct cpu id of NIM master.
(Could come up after NIM master LPM movement.)

1. check both values:
    stored value on nim client:
    # cat /etc/niminfo | grep MASTERID
    export NIM_MASTERID=00080E82D990

    actual value on nim master:
    # uname -m
    00080EC2D550

2. correct /etc/niminfo file on client
    vi /etc/niminfo and change it to the actual value
    (output of uname -m from nim master)

3. restart nimsh on nim client:
    stopsrc -s nimsh
    startsrc -s nimsh

------------------------------------