intro (doc)							intro (doc)

NAME
    intro - Introduction to nrcmd commands

SYNOPSIS

DESCRIPTION
    The nrcmd commands fall into two basic groups: regular and
    irregular.  The regular commands manipulate configuration objects such
    as DHCP Scopes and DNS Zones in a standard fashion.  The irregular
    commands do everything else that is useful.  This man page will
    describe the general pattern of the regular commands.  The
    behavior of the irregular commands will be described in their 
    individual man pages.

  Regular Command form
    Regular commands provide common functions for creating, deleting,
    viewing and editing objects of a given class.

    Create 
      <cmd> <name> create [<required args>] [<prop>=<val>]

    Delete
      <cmd> <name> delete 

    List
      <cmd> list  

    Modify
      <cmd> <name> set <prop>=<value> [<prop>=<value> ...]
        The set command takes two forms: 'set <prop> <value>' for setting
        a single properties's value, and 'set <prop>=<value> ...' for
        setting multiple values in a single command.

        Errors include:
          unknown property 
            - if <prop> is not an property name for the object
          invalid format
            - if <value> is not in a valid format
          invalid value
            - if <value> is not semantically valid
 
      <cmd> <name> get <prop>
        The get command returns the value of the named property.

      <cmd> <name> unset <prop> [<prop> ...]
        The unset command makes the named properties have no value.

      <cmd> <name> enable <feature>
        The enable command sets the value of the named feature to true.

      <cmd> <name> disable <feature>
        The enable command sets the value of the named feature to false.

      <cmd> <name> show 
        The show command displays the value of the object.

  Class specific commands (methods)
    The configuration behavior of some objects may be enhanced by the
    addition of class specific commands to perform a useful action such
    as modifying complex properties, or controlling the objects
    behavior.  

    For example, DHCP Scope objects contain lists of address ranges
    from which leases may be offered.  To manipulate this list of
    ranges, the scope command provides the commands: addRange,
    removeRange, and listRanges.

    Another example is the forceAvailable command provided by the
    lease command to tell the DHCP server that a given lease should
    be forced into the available state.
     
  Filters 
    The results of the list commands can be restricted by applying
    filters to the results.  The filter specification is similar to
    the LDAP query filter specification, but uses infix rather than
    prefix relational operators.  See the filter man page for a more
    complete description of the filter specification grammar.

  Format specifiers 
    The output format of the list and show commands can be specified
    with the format arguments.  See the format man page for a complete
    description of the format specifiers.

  Licensing
    nrcmd requires the current cluster to have a valid license.
    If the license is invalid or has expired, only the 'license'
    command will be operational; it may be used to establish a new 
    license key.  A warning will be issued upon login if the
    license will be expiring within 7 days.

  Locking
    nrcmd versions prior to CNR 6.2 are limited to a single
    session and use a locking mechanism to control access.

    In interactive mode, the program attempts at startup to get an
    exclusive lock for the cluster to which it connects.  If this
    fails, nrcmd will issue a warning, and will allow only the
    following commands to be executed: "client", "lease",
    "zone create", "help", and "force-lock".  The force-lock
    command obtains the exclusive lock indiscriminately, and 
    should be used with caution. In particular, it should not be 
    used unless you're sure that no one else is updating the cluster.

    The warning issued for interactive mode, when the lock cannot
    be obtained, is	
        408 Already locked: '<user>@<host>.<pid>'.
        Warning: unable to lock the cluster.
        You might want to use the force-lock command if
        you're sure that no one else is updating the cluster

	where
            <user> is the name of the administrator
            <host> is the name of the Unix or Windows host on which the
                   other user is running
            <pid>  is the process ID of the nrcmd or
                   Network Registrar process.  (You can use system
                   tools such as Unix "ps" or NT "Task Manager" to
                   determine if the process is still running.)

    In batch mode (when the command is entered on the command
    line), nrcmd will not attempt to obtain a lock unless the
    command is not one of the valid ones listed above.  If a lock
    is needed, it will then attempt to get it; if this fails, the
    error issued is

        408 Cannot lock cluster: Already locked: '<user>@<host>.<pid>

    where <user>, <host>, and <pid> are as above.

  Return codes 
    All nrcmd commands will return a status code as the first line of
    output.  The status codes are heavily influenced by SMTP and other
    line oriented protocols.  The first word of the line is a three
    digit status code, and the remaining words on the line are
    descriptive text that may or may not be constant for a given
    status code.  The first digit of the status code determines the
    class of the status:
      1xx - the command completed successfully, possibly with warnings
      3xx   there was some error in processing the command
      4xx   errors in communicating with the cluster database server
      5xx   there is was an internal error in the program

  Property types
    The properties that are manipulated by the set and get command
    have specific data types which determine the syntactically valid
    values.  These types are:
        AT_STRING - a string, valid inputs are:
                    * any text

        AT_INT    - an integer, valid inputs are: 
                    * decimal digits, or 
                    * 0x followed by hex digits.

        AT_BOOL   - a boolean value, valid inputs are:
                    * true, on, enabled, 1, or
                    * false, off, disabled, 0.

        AT_DATE   - a date, valid inputs are:
                    * 'forever'
                    * +<time value>

        AT_TIME   - a span of time, in seconds, valid inputs are:
                    * decimal number of seconds
                    * combination of numbers of weeks, days, hours,
                      minutes, and seconds for example: 1w2d3h4m5s.

        AT_IPADDR - an ip address, valid inputs are:
                    * dotted quad format, for example 10.24.1.2

        AT_MACADDR - a MAC address, valid inputs are:
                    * raw hex digits, for example: 010203040506
                    * hex digits separated by ':', '.', or '-', for example: 
                      01:02:03:04:05:06, 01-02-03-04-05-06, 01.02.03.04.05.06
                    * type and length, followed by hex digits, for example:
                      1,6,ab:01:cd:02:ef:03

        AT_RANGEINT  - a range restricted integer
        AT_RANGETIME - a range restricted time value
        AT_ENUMINT   - an enumerated integer
        AT_FLAGSINT  - a bitmask with named bit positions

  Validation
    Data validation will be done at configuration creation and property
    modification time.  The nrcmd CLI will check for required valid values 
    when a configuration object is created, and it will check the validity
    of property values when they are set.

    Dangling references that are created by deleting a referred-to object, 
    such as the policy for a scope, or the client class for a client will not
    be caught by the CLI.

EXAMPLES

LIMITATIONS


