lease (nrcmd)							lease (nrcmd)


NAME
    lease - Manage DHCP lease objects

SYNOPSIS
    lease list [-vpn=<vpn-name>] [-count-only]
    lease list -macaddr <mac-address> [-vpn=<vpn-name>]
    lease list -subnet <ip-address> <mask>
    lease list -lansegment <ip-address> <mask>
    lease [<vpn-name>/]<ip-address> [show]

    lease [<vpn-name>/]<ip-address> get <attribute>

    lease [<vpn-name>/]<ip-address> activate 
    lease [<vpn-name>/]<ip-address> deactivate
    lease [<vpn-name>/]<ip-address> force-available
    
    lease [<vpn-name>/]<ip-address> macaddr
    lease [<vpn-name>/]<ip-address> get-scope-name

    lease [<vpn-name>/]<ip-address> send-reservation
    lease [<vpn-name>/]<ip-address> delete-reservation

DESCRIPTION
    The lease command lets you view and manipulate current DHCP leases
    in the cluster.  
    
    When you specify the lease on which one of these commands is to
    operate, you may optionally specify a <vpn-name> in which the
    <ip-address> is to be found.  You may specify the name of a
    currently defined vpn as the <vpn-name>, or use the reserved vpn
    name "global" (without the quotes) to specify the operation on
    leases which are not in any explicitly defined vpn.  If you do
    not specify a <vpn-name>, then the session's current-vpn is used
    as a default.

    lease list [-vpn=<vpn-name>] [-count-only]
    lease list -macaddr <mac-address> [-vpn=<vpn-name>]
    lease list -subnet <ip-address> <mask>
    lease list -lansegment <ip-address> <mask>
    lease [<vpn-name>/]<ip-address> [show]
       The list command lists leases in the DHCP server. Only the
       leases in the current-vpn or specified vpn-name are listed.
       <vpn-name> may be "all" (without the quotes) to request leases
       in all vpns. If -count-only is specified, only the count of
       the number of leases is returned (no leases are displayed).

       The list -subnet command lists all leases in a subnet 
       (scopes whose address and mask match the query).

       The list -lansegment command lists all leases in a LAN
       segment, meaning all leases in scopes whose address and mask
       match the query, as well as leases in secondary scopes whose
       primary scope's address and mask match the query.

       The list -macaddr command lists all leases that are associated 
       with the specified MAC address.
       
       Note: The list -macaddr command for Network Registrar 6.3 
       and earlier clusters can be extremely slow. In release 7.0
	 and later, performance is improved. The recommended syntax 
       is -macaddr=<mac-address>.

    lease [<vpn-name>/]<ip-address> activate 
    lease [<vpn-name>/]<ip-address> deactivate
       The activate and deactivate commands tell the DHCP server 
       to make the specified lease active or inactive.  An inactive
       lease is not given out, even if it is in the available state. 
       Making a currently leased lease inactive does not affect its 
       behavior until it has expired and become available again.
    
    lease [<vpn-name>/]<ip-address> force-available
       The force-available command forces the specified lease into the
       available state.
    lease [<vpn-name>/]<ip-address> macaddr
       The macaddr command provides the MAC address associated with
       the specified lease.

     lease [<vpn-name>/]<ip-address> get-scope-name
       The get-scope-name command provides the scope to which the 
       lease belongs.
   
    lease [<vpn-name>/]<ip-address> send-reservation
       The now-deprecated send-reservation command sends an existing
       reservation immediately to the DHCP server without requiring a
       server reload.  You must first run the scope <scope-name> 
       addReservation command for this reservation.  
       The recommended sequence is:

	   nrcmd> scope <scope-name> addReservation <ip-address> <mac-address>
	   nrcmd> save
	   nrcmd> lease <ip-address> send-reservation

       This sequence ensures that the configuration database contains
       the lease and reservation as well as the running server, since
       the send-reservation command directly affects only the running
       server's in-memory database, and does not itself persist past
       the next server reload.
    
    lease [<vpn-name>/]<ip-address> delete-reservation
       The now-deprecated delete-reservation command deletes an
       existing reservation immediately from the DHCP server without
       requiring a server reload.  It is important to ensure that 
       the configuration which the DHCP server uses for the next server 
       reload also has the reservation removed. The recommended sequence
       is:

          nrcmd> lease <ip-address> delete-reservation
          nrcmd> scope  <scope-name> removeReservation <ip-address>
          nrcmd> save

    Note: The send-reservation and delete-reservation commands are 
    deprecated. Use synchronous scope-edit-mode instead. These commands
    are provided for command-syntax compatibility with prior versions
    and only support mac-address based reservations.


EXAMPLES

STATUS

SEE ALSO

    session current-vpn

PROPERTIES
  Attributes:

    address[15] (AT_IPADDR, Optional, default: <none>)
        Specifies the IP address of the lease.  The address is added at
        creation.

    binding-end-time[48] (AT_DATE, Optional, default: <none>)
        Within the DHCPlease database, holds the time at which a
        lease binding ended.

    binding-start-time[47] (AT_DATE, Optional, default: <none>)
        Within the DHCP lease database, shows the time at which a
        lease binding began.

    client-binary-client-id[39] (AT_BLOB, Optional, default: <none>)
        Displays the binary form of the client's client-identifier, if any.

    client-dns-name[1] (AT_STRING, Optional, default: <none>)
        Displays the client DNS name, which the DHCP server attempted
        (possibly successfully) to enter into the DNS server for
        a specified client.
        This attribute is related to the client-host-name, but may not be
        identical due to name collisions in the DNS server database.

    client-domain-name[3] (AT_STRING, Optional, default: <none>)
        Displays the domain (if any) to which the client's DNS name belongs.

    client-flags[7] (AT_FLAGSINT(), Optional, default: <none>)
        Displays any of the following values associated with the client
        lease state:
           2  client-id-created-from-mac-address
              Indicates that the client-id was created for internal use
              from the client supplied MAC address.  It is never
              reported externally if this is true.
           3  client-dns-name-up-to-date
              Indicates that the client-dns-name (A) is actually current
              in the DNS server database.
           5  reverse-dns-up-to-date
              Indicates that the reverse (PTR) DNS entry is current in
              the DNS database.
           9  dns-update-pending
              Indicates that a DNS operation is pending for this client.
           16 in-limitation-list
              Indicates that this lease is presently in a limitation list
              using the limitation-id shown.
        These are for internal use only:
          client-valid
          client-fqdn-present
          client-updates-name
          clear-host-name
          host-name-has-changed
          domain-name-has-changed
          use-test-before-update
          avoid-dns-retry
          dual-zone-dns-update
          client-invalid-due-to-macaddress
          used-over-limit-client-class
          synthesize-dns-name
          reservation-uses-client-id
          client-id-from-override-id
          client-id-from-string

    client-host-name[5] (AT_STRING, Optional, default: <none>)
        Displays the DNS name that the client requested the DHCP server
        to place in the DNS server.

    client-last-transaction-time[10] (AT_DATE, Optional, default: <none>)
        Displays the time when the client most recently contacted the
        DHCP server.

    client-mac-addr[2] (AT_MACADDR, Optional, default: <none>)
        Displays the MAC address which the client presented to the DHCP
        server.

    client-os-type[38] (AT_STRING, Optional, default: <none>)
        Indicates the operating system of the client. This attribute is used
        only by the updateSms keyword and has no other purpose. If you
        enable failover, the main server transmits this value to the backup
        server. The syntax of this attributes value is OS-name major.minor.:
        Operating system values are as follows:
           Microsoft Windows NT Server
           Microsoft Windows NT Advanced Server
           Microsoft Windows NT Workstation 4.0
           Microsoft Windows NT Workstation 3.51
           Microsoft Windows 2000 Professional
           Microsoft Windows 95
           Microsoft Windows 9x
           Microsoft Windows for Workgroups
           Microsoft Windows
           Dos
           Netware
           LANMAN Workstation
           LANMAN Server
           OS/2
           MAC OS

    client-override-client-id[58] (AT_BLOB, Optional, default: <none>)
        The value of the override-client-id expression for this
        client.  If it appears, it is used as the client-id for
        this client.

    client-vendor-class[71] (AT_OPTION, Optional, default: <none>)
        The most recently received client vendor class option.

    client-vendor-info[72] (AT_OPTION, Optional, default: <none>)
        The most recently received vendor-specific information
        option.

    data-source[68] (AT_ENUMINT(), Optional, default: <none>)
        Records the original source of the lease data
        and the machine from which the data was retrieved.
           0   unknown
           4   main-main
               Indicates the data originated on the  main server and
               was retrieved from the main server.
           5   backup-main
               Indicates the data originated on the backup server and
               was retrieved from the main server.
           6   main-backup
               Indicates the data originated on the main server and
               was retrieved from the backup server.
           7   backup-backup
               Indicates the data originated on the backup server and
               was retrieved from the backup.
        When viewing leases with the UI's, you will see all four
        values routinely, especially if load-balancing is enabled.
        When looking at lease history records, main-main and
        backup-backup are the usual values, but in cases where the
        lease history poller has determined that some data may be
        missing, then main-backup and backup-main can appear as
        well.

    expiration[13] (AT_DATE, Optional, default: <none>)
        Displays the date and time the lease will expire.

    flags[12] (AT_FLAGSINT(), Optional, default: <none>)
        Displays flags that describe this lease:
           1  reserved
        	  The lease is reserved for some MAC address.  The table
              that relates MAC addresses to leases is in the scope.
           3  deactivated
        	  The lease is deactivated, which means that it should
              not be used.  Any client which is using a deactivated
              lease will be NAK'ed on their next renewal.
           7  dynamic
        	  Last written by server which knew only about the lease
               because it was created by a send-reservation command.
           8  backup
        	  Indicates that the state for this lease was recorded by
               a server whose role was backup with respect to this lease.
        For internal use only:
            initialized
            valid
            failover-updated

    fwd-dns-update-config-name[53] (AT_NAMEREF(DnsUpdateConfig), Optional, default: <none>)
        Names the Dns update configuration object  used
        to perform dynamic DNS update on a forward zone.

    giaddr[69] (AT_IPADDR, Optional, default: <none>)
        If present, the contents of the last received non-zero giaddr
        field. This represents the relay agent through which the client
        and server last communicated.

    lease-renewal-time[37] (AT_DATE, Optional, default: <none>)
        Displays the earliest time the client is expected to issue
        a renewal request.

    limitation-id[46] (AT_BLOB, Optional, default: <none>)
        
        Displays the value set for a client-class or client limiting the
        number of simultaneous active leases a DHCP server can give out
        to devices on customer premises.

    relay-agent-auth[62] (AT_BLOB, Optional, default: <none>)
        The contents of the 'authentication' suboption 8 of the relay-agent
        information option 82 from this client.

    relay-agent-circuit-id[19] (AT_BLOB, Optional, default: <none>)
        Displays the circuit-id sub-option of the DHCP relay-agent
        information option 82 from this client.

    relay-agent-device-class[61] (AT_INT, Optional, default: <none>)
        The contents of the 'device-class' suboption 4 of the relay-agent
        information option 82 from this client.

    relay-agent-option[43] (AT_OPTION, Optional, default: <none>)
        Displays the contents of the relay-agent information option 82
        from the most recent client interaction.

    relay-agent-radius-class[51] (AT_STRING, Optional, default: <none>)
        Displays the contents, if any, of the RADIUS class attribute
        that was contained in the RADIUS Attributes suboption of the DHCP
        relay-agent information option 82 from this client.

    relay-agent-radius-options[64] (AT_BLOB, Optional, default: <none>)
        The contents of the 'radius' suboption 7 of the relay-agent
        information option 82 from this client.
        This suboption has additional structure that is available on
        other attributes of this class.

    relay-agent-radius-pool-name[50] (AT_STRING, Optional, default: <none>)
        Displays the contents, if any, of the RADIUS framed-pool attribute
        88 contained in the RADIUS attributes suboption of the DHCP
        relay-agent information option 82 from this client.

    relay-agent-radius-session-timeout[66] (AT_INT, Optional, default: <none>)
        If present, the contents of the RADIUS 'session-timeout' attribute
        27 that was contained in the RADIUS Attributes suboption 7 of the
        relay-agent information option 82 from this client.

    relay-agent-radius-user[49] (AT_STRING, Optional, default: <none>)
        Displays the contents, if any, of the RADIUS user attribute
        contained in the RADIUS attributes suboption of the DHCP relay-agent
        information option 82 from this client.

    relay-agent-radius-v6-pool-name[67] (AT_STRING, Optional, default: <none>)
        If present, the contents of the RADIUS 'v6-pool-name' attribute 100
        that was contained in the RADIUS Attributes suboption 7 of the
        relay-agent information option 82 from this client.

    relay-agent-radius-vendor-specific[65] (AT_BLOB, Optional, default: <none>)
        If present, the contents of the RADIUS 'vendor-specific' attribute
        26 that was contained in the RADIUS Attributes suboption 7 of the
        relay-agent information option 82 from this client.

    relay-agent-remote-id[20] (AT_BLOB, Optional, default: <none>)
        Displays the remote-id sub-option of the DHCP relay-agent
        information option 82 from this client.

    relay-agent-server-id-override[44] (AT_IPADDR, Optional, default: <none>)
        Displays the IP address in the server-id-override sub-option of the
        DHCP relay-agent information option 82 from this client.
        This value corresponds to one of two suboption numbers:
        If the IANA assigned suboption 182 is present in the packet,
        that value is returned; otherwise, if the Cisco suboption 152 is
        present, that value is returned.

    relay-agent-subnet-selection[42] (AT_IPADDR, Optional, default: <none>)
        Displays the IP address in the subnet selection sub-option
        of the DHCP relay-agent information option 82 from this client.
        This value corresponds to one of two suboption numbers:
        If the IANA assigned suboption  is present in the packet,
        that value is returned; otherwise, if  Cisco suboption 150 is
        present, that value is returned.

    relay-agent-subscriber-id[52] (AT_STRING, Optional, default: <none>)
        Displays the contents of the subscriber-id suboption of the
        relay-agent information option 82 from this client.

    relay-agent-v-i-vendor-class[63] (AT_BLOB, Optional, default: <none>)
        The contents of the 'v-i-vendor-class' suboption 9 of the
        relay-agent information option 82 from this client.

    relay-agent-vpn-id[41] (AT_BLOB, Optional, default: <none>)
        Displays the contents of the vpn-id sub-option of the DHCP
        relay-agent information option 82 from this client.
        This value corresponds to one of two suboption numbers:
        If the IANA assigned suboption 181 is present in the packet,
        that value is returned; otherwise, if Cisco suboption 151 is
        present, that value is returned.

    reservation-lookup-key[56] (AT_BLOB, Optional, default: <none>)
        The lookup key with which a reservation for this lease will be
        retrieved.

    rev-dns-update-config-name[54] (AT_NAMEREF(DnsUpdateConfig), Optional, default: <none>)
        Names the Dns update configuration object used
        to perform dynamic DNS update on a reverse zone.

    scope-name[70] (AT_NAMEREF(Scope), Optional, default: <none>)
        A reference to the scope that contains this lease.

    start-time-of-state[14] (AT_DATE, Optional, default: <none>)
        Displays the time the state changed to its current value.

    state[11] (AT_ENUMINT(), Optional, default: <none>)
        Displays the current state of the lease.
           1  available
              The lease is not currently leased by any client. Any
              client information is from the most recent client to
              lease or be offered this lease.
           2  offered
              The lease is offered to the associated client. In many
              cases, the database is not written with information
              concerning offering a lease to a client since there is
              no requirement to update stable storage with this
              information.
           3  leased
              The lease is currently leased to the client whose
              information appears in the lease.
           4  expired
              The client specified has not renewed the lease, and it
              expired. Upon expiration the DNS information for this
              client was scheduled for removal.
           5  unavailable
              The lease is unavailable.  It was made unavailable because
              of some conflict. A ping attempt might have shown that the
              another client using the, or the DHCP server might have
              detected another DHCP server handing out  this IP address,
              or a DHCP client might have declined the lease. Use
              start-time-of-state to determine when the lease became
              unavailable, and look in the log file around that time to
              determine exactly why the lease became unavailable.
           6  released
              The client specified has released the lease, but the
              server was configured to apply a 'release-grace-period'.
              The lease won't be made available until the
              grace-period expires.
           7  other-available
              Used only when failover is enabled.  A lease in the
              other-available state is available for allocation by the
              other server in the failover pair, but not available for
              allocation by this server.
           8  pending-available
              Used only when failover is enabled.  A lease in the
              pending-available state will be available as soon as
              this server can synchronize its available state with
              the other server.

    user-defined-data[60] (AT_STRING, Optional, default: <none>)
        This string value is associated with the lease in order to allow
        customer applications to relate the lease record to other
        databases.  It is not used directly by the DHCP server, but may be
        read and written by extensions and expressions.

    vendor-class-id[36] (AT_STRING, Optional, default: <none>)
        Displays the vendor-class-id as offered in a DHCP request option 60.

    vpn-id[40] (AT_INT, Optional, default: 0)
        Displays the identifier of the DHCP VPN that contains this lease.

