ainfo - display array information


SYNOPSIS

       ainfo [options...] request


DESCRIPTION

       The  ainfo  command is used to display various information
       about arrays known to the  array  services  daemon.   This
       information could be useful for both interactive users and
       shell scripts, and can be displayed in formats appropriate
       for  either.   The type of information displayed is deter­
       mined by the request argument which is described below.

       Many of the options are used to narrow down a  request  or
       to  specify a particular element to be described.  Not all
       of the options make sense for every request.  Options that
       are  not  used  by  a  particular  request will be ignored
       silently.  The valid options include:

       --aa arrayname or --aarrrraayy arrayname
            Specifies the name of a specific  array  about  which
            information is required.  If not specified, the array
            services daemon's default destination will be used.

       --bb or --bbrriieeff
            Brief: specifies brief output, intended  for  use  by
            shell  scripts.   This  is the same as specifying "-f
            2".

       --DD or --ddiirreecctt
            When used with --ss, indicates that the request  should
            be sent directly to the specified server, rather than
            forwarded to that server by the local array  services
            daemon.   This  will  fail  on systems that use array
            services  authentication  unless  the  -Kl  and   -Kr
            options are also specified.  --DD is the default behav­
            ior under normal circumstances (but see the  descrip­
            tion of the AARRRRAAYYDD_FFOORRWWAARRDD variable, below).

       --FF or --ffoorrwwaarrdd
            When  used with --ss, indicates that the request should
            be forwarded to the specified server  via  the  local
            array  services  daemon, rather than sent directly to
            it.  --FF will become the default behavior if the value
            of  the  AARRRRAAYYDD_FFOORRWWAARRDD  environment  variable begins
            with the letter "Y" (as in "yes"; it  may  be  either
            upper or lower case).

       --ff number or --ffoorrmmaatt number
            Format:  many  requests can display their information
            in several formats.  This option is  used  to  select
            which  format is to be used.  See the descriptions of

            available  for  each.   The  default format is always
            "1", which is typically appropriate for a human user.
            The  other  formats  are  usually intended for use by
            shell scripts.  The output generated by format 1  for
            a given request may change from version to version of
            ainfo as new fields are added or modified.   However,
            unless  otherwise  specified, the output generated by
            the other formats  generally  should  not  change  in
            future  versions  of  ainfo, so that old scripts will
            still run properly.  Instead,  new  formats  will  be
            added to handle the new or modified fields.

       --hh ASH or --aasshh ASH or --aarrsseessss ASH
            Specifies  a  particular  array  session handle about
            which information is required.

       --ii PID or --ppiidd PID or --pprroocceessss PID
            Specifies a particular process ID about which  infor­
            mation is required.

       --KKll key or --llooccaallkkeeyy key
            Use  key for the local authentication key when commu­
            nicating directly with a remote array  services  dae­
            mon.   key  is an unsigned 64-bit value.  The default
            local key is obtained from the  environment  variable
            AARRRRAAYYDD_LLOOCCAALLKKEEYY;  if  that  does not exist, no key is
            used.  The actual role played by key depends  on  the
            authentication  method  used  by  array services in a
            particular configuration.  In general, it is not used
            when  communicating  with an array services daemon on
            the local machine.

       --KKrr key or --rreemmootteekkeeyy key
            Use key for the remote authentication key when commu­
            nicating  directly  with a remote array services dae­
            mon.  key is an unsigned 64-bit value.   The  default
            remote  key is obtained from the environment variable
            AARRRRAAYYDD_RREEMMOOTTEEKKEEYY; if that does not exist, no  key  is
            used.   The  actual role played by key depends on the
            authentication method used by  array  services  in  a
            particular configuration.  In general, it is not used
            when communicating with an array services  daemon  on
            the local machine.

       --ll or --llooccaall
            Local:  several requests normally display information
            about several different machines in an  array.   This
            option  indicates  that  only  information  about the
            machine running the array services daemon  (typically
            the  local  machine)  should  be displayed.  Requests
            that use the -a option will generally ignore it if -l
            is specified.

            Specifies the port address of the array services dae­
            mon.  Defaults to the value of the AARRRRAAYYDD_PPOORRTT  envi­
            ronment  variable  if  present,  or the standard port
            number of the "sgi-arrayd" service otherwise.

       --ss server or --sseerrvveerr server
            Specifies the hostname or IP  address  of  the  array
            services daemon.  Defaults to the value of the AARRRRAAYYDD
            environment variable if present, or "localhost"  oth­
            erwise.

       --tt value or --ttiimmeeoouutt value
            Specifies  the  timeout  value  (in  seconds) used in
            waiting for a response from the array  services  dae­
            mon.   The  default is 15 seconds.  It should only be
            necessary to specify  this  option  on  very  heavily
            loaded systems.

       --vv   Verbose  messages:  display  additional progress mes­
            sages.  Repeated occurrences (either "-v -v  ..."  or
            "-vv...")  increases  the verbosity, although this is
            generally only useful for debugging ainfo itself.


REQUESTS

       Several different types of information can  be  requested.
       In  most  cases, each type of information can be displayed
       in several formats.  The keyword used to specify a partic­
       ular  request  may be in upper or lower case, and for some
       requests, it may only be necessary to  specify  a  leading
       substring of the keyword.  The following descriptions will
       show the minimum leading  substring  of  each  keyword  in
       upper case.

   ARRAYs
       Displays  information  about all arrays known to the array
       services daemon.  The -a, -h, -i and -l  options  are  all
       ignored with this request.

       Format 1 output:
            AArrrraayyss kknnoowwnn ttoo aarrrraayy sseerrvviicceess ddaaeemmoonn target-info
            AARRRRAAYY name
                IIDDEENNTT id
                ATTRIBUTES
                    array_attr_1
                    array_attr_2...

            ARRAY ...

            If the -p or -s options were specified, that informa­
            tion will be included in target-info.   name  is  the
            ASCII   name  of  the  array,  as  specified  in  the
            arrayd.conf file.  id is the array identifier number,
            as  specified  in  the arrayd.conf file with an ARRAY

            hexadecimal  preceded by "0x".  The array_attr_N val­
            ues are arbitrary strings assigned to  the  array  by
            the system administrator.  If no array attributes are
            present, the "ATTRIBUTES" line will not be printed.

       Format 2 output:
            aarrrraayy name #attributes array_attr_1 array_attr_2...

       Format 3 output:
            aarrrraayy    name     id     #attributes     array_attr_1
            array_attr_2...

            This  is  the  same as format 2, with the addition of
            the id field.

   ASH
       Displays the array session handle of the process specified
       by the -i option.  If the -i option is not specified, then
       the array session handle for the current process  will  be
       displayed.   The process is assumed to reside on the local
       machine.  The -a, -h and -l options are ignored.

       Format 1 output:
            AArrrraayy sseessssiioonn hhaannddllee ooff pprroocceessss pid:: ash

            pid is the process ID specified  by  the  -i  option.
            ash  is  the array session handle of process pid.  It
            is displayed in hex preceded by the string "0x".

       Format 2 output:
            pid

   DFLTArray
       Displays information about the default array that is  used
       by  the array services daemon when one has not been speci­
       fied explicitly.  The  -a,  -h,  -i  and  -l  options  are
       ignored.   The format of the output is nearly identical to
       that of the ARRAYS request:

       Format 1 output:
            DDeeffaauulltt aarrrraayy aaccccoorrddiinngg ttoo aarrrraayy sseerrvviicceess ddaaeemmoonn target-info
            AARRRRAAYY name
                AATTTTRRIIBBUUTTEESS
                    array_attr_1
                    array_attr_2......

            If the -p or -s options were specified, that informa­
            tion  will  be  included in target-info.  name is the
            ASCII  name  of  the  array,  as  specified  in   the
            arrayd.conf  file.  The array_attr_N values are arbi­
            trary strings assigned to the  array  by  the  system
            administrator.   If  no array attributes are present,
            the "ATTRIBUTES" line will not be printed.

            aarrrraayy name #attributes array_attr_1 array_attr_2...

   MACHines
       Displays information about each of  the  machines  in  the
       array  specified  by  the  -a  option.   The -h, -i and -l
       options are ignored.

       Format 1 output:
            MMaacchhiinneess iinn array-name target-info
            MMAACCHHIINNEE name
                HHOOSSTTNNAAMMEE hostname
                PPOORRTT     portnum
                IIPP_AADDDDRR  IPaddress
                IIDDEENNTT    id
                AATTTTRRIIBBUUTTEESS
                    attr1
                    attr2......

            MMAACCHHIINNEE ......

            target-info includes information about the array ser­
            vices  daemon  that  was contacted and the particular
            array being described.  If the -a, -p or  -s  options
            were  specified, that information will be included in
            target-info.  name is  the  "familiar"  name  of  the
            machine, while hostname is the official network host­
            name of the machine  and  IPaddress  is  the  network
            address  corresponding  to that hostname.  portnum is
            the port number of the machine's array services  dae­
            mon.   id  is  the server identifier of the machine's
            array services daemon.  It is  always  printed  as  a
            4-digit  hexadecimal  number  preceded by "0x" unless
            the array services daemon  specified  in  target-info
            does  not have a SSEERRVVEERR IIDDEENNTT entry for that machine,
            in which case "unknown" is printed.  The attrN values
            are arbitrary strings assigned to this machine by the
            system administrator.  If a particular machine has no
            machine  attributes,  the AATTTTRRIIBBUUTTEESS line will not be
            displayed.

       Format 2 output:
            mmaacchhiinnee name hostname portnum IPaddress #attrs attr1 attr2......

            The output for each machine will appear on  a  single
            line without any intervening newlines.

       Format 3 output:
            hostname
            hostname......

            This  format  would be useful in scripts that need to
            contact each machine in an array via the network.

            mmaacchhiinnee name hostname portnum IPaddress id #attrs attr1 attr2...

            This is the same as format 2, with  the  addition  of
            the  ident  value  just prior to the attributes.  The
            output for each machine will appear on a single  line
            without any intervening newlines.

   NEWASH
       Obtains  a  new  global array session handle for the array
       specified by the -a option.  This does not actually  start
       a  new  array session, it simply allocates a unique handle
       for one.  The -h, -i and -l options are all ignored.

       Format 1 output:
            AAllllooccaattiinngg nneeww gglloobbaall AASSHH target-info
            array-session-handle

            target-info includes information about the array ser­
            vices  daemon  that  was contacted and the particular
            array for which the handle was allocated.  If the -a,
            -p  or  -s  options  were specified, that information
            will be included in target-info.  The  array-session-
            handle is displayed as a 64-bit hex value preceded by
            the string "0x".

       Format 2 output:
            array-session-handle

            The array-session-handle is displayed as a 64-bit hex
            value preceded by the string "0x".

   NODEINFO
       Displays  information  about  the overall configuration of
       each machine in the array specified by the -a  option,  or
       of the server machine only if the -l option was specified.
       The -h and -i options are ignored.

       Format 1 output:
            NNooddee iinnffoorrmmaattiioonn ffoorr target-info
            MMAACCHHIINNEE name
                VVEERRSSIIOONN  vers
                #pe PPRROOCCEESSSSOORR BBOOAARRDD[SS]
                    BBOOAARRDD:: TTYYPPEE btype   SSPPEEEEDD speed
                        CCPPUU::   TTYYPPEE ctype   RREEVVIISSIIOONN crev
                        FFPPUU::   TTYYPPEE ftype   RREEVVIISSIIOONN frev

                    BBOOAARRDD......

                #ip IIPP IINNTTEERRFFAACCEE[SS]  HHOOSSTTNNAAMMEE hostname   HHOOSSTTIIDD hostid
                    DDEEVVIICCEE dev  NNEETTWWOORRKK netaddr  AADDDDRREESSSS ipaddr status
                    DDEEVVIICCEE......

                #gfx GGRRAAPPHHIICCSS IINNTTEERRFFAACCEE[SS]

                    TTYYPPEE......

                MMEEMMOORRYY
                    memsize MMBB MMAAIINN MMEEMMOORRYY
                    IINNTTEERRLLEEAAVVEE interleave

                AARRRRAAYY MMAACCHHIINNEE arraymach
                    AARRRRAAYY SSEERRVVIICCEESS PPOORRTT port
                    #attr AATTTTRRIIBBUUTTEESS
                            attr
                            attr......

            MMAACCHHIINNEE ......

            target-info includes information about the array ser­
            vices  daemon  that  was contacted and the particular
            machine or array being described.  If the -a,  -p  or
            -s  options  were specified, that information will be
            included in target-info.  name is the hostname of the
            machine  according  to  the  machine's array services
            daemon.  This is  typically  the  value  returned  by
            gethostname(2)  on  that  machine,  though the system
            adminstrator can override this value by specifying  a
            LOCAL  HOSTNAME  entry  in  the machine's arrayd.conf
            file.  vers is the  NodeInfo  version  number.   This
            will change whenever the output format is modified in
            some way.  The minor number of the version is  rolled
            when  additional  fields  are added to the end of any
            line or section.  The major number is rolled if  pre­
            viously  existing  fields are changed.  Programs that
            parse the output of ainfo should inspect  this  value
            and act accordingly if it does not recognize the ver­
            sion number.

            The fields in the PPRROOCCEESSSSOORR BBOOAARRDD and GGRRAAPPHHIICCSS IINNTTEERR­­
            FFAACCEE sections are taken directly from the inventory_t
            structures  returned  by  getinvent(3).   These   are
            described in <sys/invent.h>.

            hostname  is  the  hostname  of the machine's primary
            network interface as  determined  by  gethostname(2).
            This is typically the same as name unless a different
            machine name was  specified  with  a  LOCAL  HOSTNAME
            entry  in  the machine's arrayd.conf file.  hostid is
            the machine's official hostid, as obtained  by  geth­
            ostid(2).   It  is  displayed as a hex value.  dev is
            the device name of  a  particular  network  interface
            (for example, "hip0").  net is the network address of
            the interface; this is generally the  IP  address  of
            the  interface  AND'ed  with the interface's netmask.
            ip is the official IP address of the interface.  sta­
            tus  is  either the string "UP" or "DOWN", indicating
            whether or not the interface is active.

            -l  has  not been specified.  arraymach is the "logi­
            cal" name of the machine in the array.  In most cases
            this  will  be  the  same  as the machine's hostname,
            though the system administrator can override this  in
            the  machine's arrayd.conf file.  port is the IP port
            number of the array services daemon on that  machine.
            attr  is an attribute string for that machine.  There
            may be zero or more of these, depending on  the  con­
            figuration.

            The remaining fields are fairly self explanatory.

       Format 2 output:
            nnooddeeiinnffoo..ttoopp vers name
            nnooddeeiinnffoo..ppee #pe btype//speed//ctype//crev//ftype//frev btype//...
            nnooddeeiinnffoo..iipp hostname hostid #ip dev//netaddr//ipaddr//status dev//...
            nnooddeeiinnffoo..ggffxx #gfx gtype//ctrlr//unit//state gtype//...
            nnooddeeiinnffoo..mmeemm memsize interleave
            nnooddeeiinnffoo..aamm arraymach port #attrs attr attr...

            The fields of individual interface entries (for exam­
            ple, between the type, ctrlr, unit and  state  fields
            of  a  graphics interface entry) are separated by "/"
            characters with no intervening spaces.  Unlike format
            1,  the  array  machine  information  will be present
            whether or not -l was specified; if -l was specified,
            arraymach  will  be "<n/a>" and port will be -1.  The
            output for each machine  will  appear  on  exactly  6
            lines.

   PIDs
       This  is  a  synonym  for the PROCESSES request, described
       below.

   PROCesses
       Displays the process IDs of those processes on  the  local
       machine running in the array session whose handle is spec­
       ified by the -h option.  The -a, -i  and  -l  options  are
       ignored for this request.

       Format 1 output:
            PPrroocceessss IIDDss iinn AASSHH array-session-handle
                    process-ID
                    process-ID......

       Format 2 output:
            process-ID process-ID......

            This  format  is  convenient  with  commands  such as
            kill(1).

       Format 3 output:
            process-ID,process-ID,......

            of the ps(1) command.

   SESSIONs
       Displays  the  array  session  handles of the global array
       sessions in the array specified by the -a option, or  only
       on  the  server machine if -l is specified.  The -h and -i
       options are ignored.

       Format 1 output:
            GGlloobbaall aarrrraayy sseessssiioonnss target-info
                    array-session-handle-1
                    array-session-handle-2......

            target-info includes information about the array ser­
            vices  daemon  that  was contacted and the particular
            array being described.  If the -a, -p or  -s  options
            were  specified, that information will be included in
            target-info.  Each array-session-handle is  displayed
            as a 64-bit hex value preceded by the string "0x".

       Format 2 output:
            array-session-handle-1 array-session-handle-2...

            Each  array-session-handle  is  displayed as a 64-bit
            hex value preceded by the string "0x".


NOTES

       The array services daemon (arrayd(1M)) must be running  on
       all  machines  about  which information is being obtained.
       It does not necessarily have to be running on the  machine
       that executes "ainfo(1)".


SEE ALSO

       array(1), arrayd(1M), arrayd.conf(4).


Man(1) output converted with man2html