Cisco CNS Network Registrar User's Guide, 6.1
Appendix - DHCP Extension Dictionary
Downloads: This chapterpdf (PDF - 397.0KB) The complete bookPDF (PDF - 6.99MB) | Feedback

DHCP Extension Dictionary

Table Of Contents

DHCP Extension Dictionary

Extension Dictionary Entries

Decoded DHCP Packet Data Items

Request Dictionary

Response Dictionary

Extension Dictionary API

Tcl Attribute Dictionary API

Tcl Request and Response Dictionary Methods

Tcl Environment Dictionary Methods

DEX Attribute Dictionary API

DEX Request and Response Dictionary Methods

DEX Environment Dictionary Methods


DHCP Extension Dictionary


This appendix describes the DHCP extension dictionary entries and the application program interface (API) to the extension dictionary. It describes the data items available in the request and response dictionaries, and the calls to use when accessing dictionaries from Tcl extensions and shared libraries.

Extension Dictionary Entries

A dictionary is a data structure that contains key-value pairs. There are two types of dictionaries: the attribute dictionaries the request and response dictionaries use, and the environment dictionary. This section describes the request and response dictionaries; the environment dictionary entries are described in the "Tcl Environment Dictionary Methods" section.

Decoded DHCP Packet Data Items

The decoded DHCP packet data items represent the information in the DHCP packet, and are available in both the request and response dictionaries. These dictionaries provide access to considerably more internal server data structures than just the decoded request and decoded response.

All of the options followed by an asterisk (*) are multiple, which means that there may be more than one value associated with each option. In the DHCP/BOOTP packet, all of these data items appear in the same option. However, in the extension interface, these multiple data items are accessible through indexing.

You can access options that do not have names in Table C-2 as option-n, where n is the option number. All fields are read/write. Table C-1 describes the field values for the options.

Table C-1 DHCP and BOOTP Fields 

Name
Value

chaddr

blob (sequence of bytes)

ciaddr

IP address

file

string

flags

16-bit unsigned integer

giaddr

IP address

hlen

8-bit unsigned integer

hops

8-bit unsigned integer

htype

8-bit unsigned integer

op

8-bit unsigned integer

secs

16-bit unsigned integer

siaddr

IP address

sname

string

xid

32-bit unsigned integer

yiaddr

IP address


Table C-2 lists the DHCP and BOOTP options.

Table C-2 DHCP and BOOTP Options 

Name (*=multivalue)
Number
Value

all-subnets-local

27

byte-valued boolean

arp-cache-timeout

35

int

boot-file

61

string

boot-size

13

16-bit unsigned integer

broadcast-address

28

IP address

cablelabs-client-
configuration

122
suboption:

blob (sequence of bytes)

ccc-primary-dhcp-server

1

IP address

ccc-secondary-dhcp-
server

2

IP address

ccc-provisioning-server

3

blob (the first byte must be the type byte, with 0 for RFC 1035 encoding, and 1 for IP address encoding, for which the address must be in network order)

ccc-as-backoff-retry-
blob

4

12-byte blob (3 unsigned 4-byte integers, which must be in network order); configures the Kerberos AS-REQ/AS-REP timeout, backoff, and retry mechanism

ccc-ap-backoff-retry-
blob

5

12-byte blob (3 unsigned 4-byte integers, which must be in network order); configures the Kerberos AP-REQ/AP-REP timeout, backoff, and retry mechanism

ccc-kerberos-realm

6

variable-length blob (an RFC 1035 style name); a Kerberos realm name is required

ccc-use-tgt

7

1-byte unsigned integer boolean; indicates whether to use a Ticket Granting Ticket (TGT) when obtaining a service ticket for one of the application servers

ccc-provisioning-timer

8

1-byte unsigned integer; defines the maximum time allowed for the provisioning process to complete

ccc-ticket-control-mask

9

2-byte unsigned integer, in host order

ccc-kdc-addresses-blob

10

variable-length (multiple of 4) IP address, in network order

cisco-vpn-id

168

blob (sequence of bytes)

cookie-servers*

8

IP address

default-ip-ttl

23

8-bit unsigned int

default-tcp-ttl

37

8-bit unsigned int

dhcp-class-identifier

60

string

dhcp-client-identifier

61

blob (sequence of bytes)

dhcp-lease-time

51

int

dhcp-max-message-size

57

16-bit unsigned integer

dhcp-message

56

string

dhcp-message-type

53

blob (sequence of bytes)

dhcp-option-overload

52

blob (sequence of bytes)

dhcp-parameter-request-list*

55

8-bit unsigned integer

dhcp-parameter-request-
list-blob

55

blob (sequence of bytes)

dhcp-rebinding-time

59

int

dhcp-renewal-time

58

int

dhcp-requested-address

50

IP address

dhcp-server-identifier

54

IP address

dhcp-user-class-id

77

string

domain-name

15

string

domain-name-servers*

6

IP address

extensions-path

18

string

finger-servers*

73

IP address

font-servers*

48

IP address

host-name

12

string

ieee802.3-encapsulation

36

8-bit unsigned integer

impress-servers*

10

IP address

interface-mtu

26

16-bit unsigned integer

ip-forwarding

19

byte-valued boolean

irc-servers*

74

IP address

log-servers*

7

IP address

lpr-servers*

9

IP address

mask-supplier

30

byte-valued boolean

max-dgram-reassembly

22

16-bit unsigned integer

merit-dump

14

string

mobile-ip-home-agents*

68

IP address

name-servers*

5

IP address

netbios-dd-servers*

45

IP address

netbios-name-servers*

44

IP address

netbios-node-type

46

blob (sequence of bytes)

netbios-scope

47

string

nis+-servers*

65

IP address

nis+domain

64

string

nis-domain

40

string

nis-servers*

41

IP address

nntp-servers*

71

IP address

non-local-source-routing

20

byte-valued boolean

ntp-servers*

42

IP address

path-mtu-aging-timeout

24

int

path-mtu-patheau-tables*

25

16-bit unsigned integer

perform-mask-discovery

29

byte-valued boolean

policy-filters*

21

IP address (there can be two policy filters, each one having its own IP address)

pop3-servers*

70

IP address

relay-agent-info

82
suboption:

blob (sequence of bytes)

relay-agent-circuit-id

1

(deprecated in favor of relay-agent-circuit-id-data)

relay-agent-circuit-id-
data

1

blob (does not require the suboption number as the first byte); accesses and manipulates the relay-agent-circuit-id data from a DHCP request or response

relay-agent-remote-id

2

(deprecated in favor of relay-agent-remote-id-data)

relay-agent-remote-id-
data

2

blob (does not require the suboption number as the first byte); accesses and manipulates the relay-agent-remote-id data from a DHCP request or response

relay-agent-device-class

4

(deprecated in favor of relay-agent-device-class-data)

relay-agent-device-
class-data

4

4-byte unsigned integer; represents the device class, or individual attributes of the cable modem (RFC 3256)

relay-agent-subnet-
selection-data

5

IP address

cisco-subnet-selection

150

IP address

cisco-vpn-id

151

blob (the first byte defines the type of the option, where 0 means the rest of the option contains a VRF name as a string; if the first byte is 1, the rest of the option contains an RFC 2685-style VPN ID; typically 7 additional bytes)

cisco-vpn-id-data

151

blob (does not require a suboption number as the first byte)

cisco-server-id-override

152

IP address

relay-agent-vpn-id-data

181

string

relay-agent-server-id-
override-data

182

IP address

resource-location-servers*

11

IP address

root-path

17

string

router-discovery

31

byte-valued boolean

router-solicitation-address

32

IP address

routers*

3

IP address

smtp-servers*

69

IP address

static-routes*

33

IP address

streettalk-directory-
assistance-servers*

76

IP address

streettalk-servers*

75

IP address

subnet-mask

1

IP address

subnet-selection

118

IP address

swap-server

16

IP address

tcp-keepalive-internal

38

int

tcp-keepalive-garbage

39

byte-valued boolean

tftp-server

66

string

time-offset

2

int

time-servers*

4

IP address

trailer-encapsulation

34

byte-valued boolean

vendor-encapsulated-options

43

blob (sequence of bytes)

vpn-id

167

blob (sequence of bytes)

www-servers*

72

IP address

x-display-managers*

49

IP address


Table C-3 lists the decoded packet fields.

Table C-3 Decoded Packet Field 

Data Item
Value
Description

dump-packet

int

When the value of dump-packet is set to 1, Network Registrar dumps the current decoded DHCP/BOOTP packet to the log file. An extension can put the value 1 into this data item at multiple points in its execution. This may be useful when debugging extensions.

mac-address

blob

MAC address that came in the client packet. The first byte is the hardware type, the second is the hardware length, and the remaining (up to 16) is the information from the chaddr read just after post-packet-decode. This is a useful aggregation of the htype, hlen, and chaddr fields of the DHCP packet. When read it is constructed from these fields; when written it is placed into these fields.


Request Dictionary

Table C-4 lists the data items that you can set in the request dictionary at any time. The DHCP server reads them at various times. Unless indicated otherwise, all operations are read/write.

Table C-4 Request Dictionary Specific Data Items 

Data Item
Value

allow-bootp

int

If set to 1, allows BOOTP for any scope for this request. Read during scope selection and while checking for lease acceptability.

allow-dhcp

int

If set to a 1, allows DHCP for any scope for this request. Read during scope selection and while checking for lease acceptability.

allow-dynamic-bootp

int

If set to a 1, allows dynamic BOOTP for any scope for this request. Read during scope selection and while checking for lease acceptability.

bootp-reply-options

blob

Overrides any bootp-reply-options in any policy. Read when gathering data for the output packet.

client-class-name

string

Name of the client-class used to complete the client information (if any).

client-class-policy

string

Name of the policy that is associated with the client-class. If set, it must be with the name of a policy that was already configured in the server.

client-domain-name

string

Domain name that the client wants to use. It may not exist, in which case the DHCP server uses the domain name specified in the scope. Read when queuing the request for DNS update just prior to the update of stable storage.

client-host-name

string

Host name for the client in DNS; read when queuing in the request for a DNS update just before updating stable storage. Places the actual name in DNS when that operation completes.

client-id

blob

Client identification that the server uses to track the client. May be the client-id sent with a request or internally generated from the MAC address. See client-id-created-from-mac-address.

client-id-created-from-mac-address

int

If set to 1, the client-id was created from the MAC address and not be used in reporting and never the client-id not created from a MAC address.

client-ipaddress

IP address

IP address from which the client sent its packet. Note that it could be zero if the client does not yet have an IP address.

client-lookup-id

blob

Client lookup ID calculated by the client-lookup-id expression of the client-class.

client-mac-address

blob

MAC address stored in the client object associated with the request dictionary. Has the same format (and was created from) the mac-address described in Table C-3.

client-os-type

int

Change the client entry of the request packet by setting this at the pre-client-lookup or post-client-lookup extension points. Can also be read at check-lease-acceptable, but cannot be set there. To set the value, you must first set the os-type in the post-packet-decode request dictionary.

client-policy

string

Name of the policy that is associated with the client entry. If set, must be the name of a preconfigured policy in the DHCP server.

client-port

int

Port from which the client sent its request.

client-requested-host-name

string

Host name that the client requested be used for the DNS update. The DHCP server saves this information so that a change can be detected.

client-wants-nulls-in-strings

int

Determines whether the DHCP server returns strings to the client terminated with a null. If set to 1, the server terminates strings with a null. If set to 0, it does not terminate strings with a null. Set before post-packet-decode and read when encoding the response packet after pre-packet-encode.

dhcp-reply-options

blob

Overrides any DHCP reply options specified in any policy. Read when gathering data for the output packet.

import-packet

int

Determines whether the server treats the packet as if it came from an import client. If set to 1, the server treats the client as an import client and performs all DNS operations on it before sending an ACK. Read when checking the server import mode (right after post-packet-decode), getting ready for DNS processing, and when setting the reply address.

limitation-count

int

Number of simultaneous users allowed with the same limitation-id.

limitation-id

blob

Calculated by the limitation-id expression (if any) for the client-class in which this request falls.

limitation-id-null

int

Set to 1(true) if the limitation-id is null, 0 (false) if another value.

log-client-criteria-processing

int

If set to a 1, logs the criteria processing for the client for this request. Read when trying to acquire a new lease for a client that does not have one, and when checking for lease acceptability.

log-client-detail

int

If set to a 1, logs the client-class processing for this request. Read at the end of client-class processing, after post-client-lookup.

log-dns-update-detail

int

If set to a 1, logs DNS update details for this request.

log-failover-detail

int

If set to a 1, logs a more detailed level of failover activity, such as all failover state changes.

log-incoming-packet-detail

int

If set to a 1, checks whether detailed incoming packet tracing occurred for this request, so that you do not need to put a separate trace on it. Read before packet decoding and the first extension point.

log-incoming-packets

int

If set to a 1, logs the incoming packets for this request. Read after post-decode-packet.

log-ldap-create-detail

int

If set to a 1, logs messages whenever the DHCP server initiates a lease state entry creation to, receives a response from, or retrieves a result or error message from an LDAP server.

log-ldap-query-detail

int

If set to a 1, logs messages whenever the DHCP server initiates a query to, receives a response from, or retrieves a query result or an error message from an LDAP server.

log-ldap-update-detail

int

If set to a 1, logs messages whenever the DHCP server initiates an update lease state to, receives a response from, or a retrieves a result or error message from an LDAP server.

log-leasequery

int

If set to a 1, logs messages when leasequery packets are processed without internal errors and result in an ACK or a NAK.

log-incoming-packets

int

If set to a 1, logs incoming packets for this request. Read after post-decode-packet.

log-missing-options

int

If set to a 1, logs missing options (those a client requests but the DHCP server cannot return). Read while gathering data for the response.

log-outgoing-packet-detail

int

If set to a 1, logs a detailed dump of the outgoing packet for this request. Read after pre-packet-encode and just before sending the packet to the DHCP client.

log-unknown-criteria

int

If set to a 1, logs any unknown criteria specified in the client's inclusion or exclusion criteria for this request. Read when acquiring a new client lease or checking lease acceptability for an existing client.

namespace-description

string (read-only)

Description for the namespace. See namespace-name for details.

namespace-id

int (read-only)

Namespace identifier. See namespace-name for details.

namespace-name

string (read-only)

Name of the namespace. The request dictionary does not have valid values for these items at post-packet-decode, but does at all other extension points, because the namespace has not yet been determined. This is so that a script can change the vpn-id option or suboption at post-packet-decode and thereby affect the namespace used for a lease.

namespace-vrf-name

string (read-only)

Virtual routing and forwarding table identifier for the namespace. See namespace-name for details.

namespace-vpn-id

blob, typically 7 bytes (read-only)

Virtual private network identifier for the namespace. See namespace-name for details.

ping-clients

int

If set to a 1, performs a ping before offering a lease for this request. Read just before determining if a lease is acceptable for a client.

reply-to-client-address

int

If set to 1, the server sends the response packet to the client-ip-address and the client-port instead of using the RFC-mandated algorithm.

selection-criteria

string

Comma-separated string that contains the scope's selection criteria.

selection-criteria-excluded

string

Comma-separated string that contains the scope's exclusion criteria.

send-ack-first

int

If set to a 1, updates DNS after the ACK for DHCP requests. Read just before initiating the DNS operation.

transaction-time

int

Time, in seconds since 1970, that the input packet was decoded.

update-dns-for-bootp

int

If set to a 1, updates DNS for BOOTP requests for this request. Read just before initializing the DNS operation for BOOTP.

verbose-logging

int

If set to a 1, logs verbose messages for this request. Read at various times during processing.


Response Dictionary

Table C-5 lists the data items you can set in the response dictionary at any time. The DHCP server reads them at various times. Unless indicated otherwise, the operation is read/write.

Table C-5 Response Dictionary Specific Data Items 

Data Item
Value

auto-configure

int

Network Registrar can ask and be notified if autoconfiguration should be disabled on the local subnet. Writing an extension script to return yiaddr=0.0.0.0 and setting this option (0xFB) to 0 prevents a Windows 2000 RC3 DHCP client from autoconfiguring. Allows clients to choose a link-local IP address so that they can communicate with other hosts on the same link.

client-domain-name

string (read-only)

From the client information in the lease, the domain name that the client wants to use. It might not exist, in which case the DHCP server uses the domain name specified in the scope. Read when queuing the request for DNS update just prior to the update of stable storage.

client-expiration-time

int

Absolute time value of the lease expiration time last given to the client.

client-host-name

string

From the client information in the lease, the host name that the DHCP server puts into DNS. Read when queueing the request for a DNS update just before updating stable storage.

client-id

blob

From the client information in the lease, the client identification that the server used to keep track of the client. This might be the client-id sent with a request or a client-id internally generated from the MAC address.

client-id-created-from-mac-address

int (read-only)

From the client information in the lease. If set to 1, the client-id must be created from the MAC address and should not be used in reporting.

client-last-transaction-time

int (read-only)

Time, in seconds, since 1970, that the DHCP server last heard from this client.

client-mac-address

blob

From the client information in the lease, the MAC address stored in the client object associated with the request dictionary. Has the same format as (and was created from) the MAC address.

client-os-type

int

Change the client entry of the request packet by setting this at the pre-client-lookup or post-client-lookup extension points. Can also be read at check-lease-acceptable, but cannot be set there. To set the value, you must first set the os-type in the post-packet-decode request dictionary.

client-limitation-id

blob (read-only)

Limitation identifier of the client associated with the current lease.

client-requested-host-name

string

From the client information in the lease, the host name that the client requested for the DNS update.

domain-name-changed

int

If set to 1, the domain name in the current packet differs from the domain name used in the DNS update. Read after check-lease-acceptable and before pre-packet-encode.

host-name-changed

int

If set to 1, the host name in the current packet differs from that used in the DNS update. Read after check-lease-acceptable and before pre-packet-encode.

host-name-in-dns

int

If set to 1, the host name is in DNS. Read after check-lease-acceptable and before pre-packet-encode. Written after the host name goes into DNS.

lease-deactivated

int (read-only)

If set to 1, reports that the lease is de-activated.

lease-ipaddress

IP address (read-only)

IP address of the lease that the DHCP server uses in processing.

lease-namespace-description

string (read-only)

Description for the namespace stored with a response's lease.

lease-namespace-id

int (read-only)

Identifier for the namespace stored with a response's lease.

lease-namespace-name

string (read-only)

Name of the namespace stored with a response's lease.

lease-namespace-vrf-name

string (read-only)

Virtual routing and forwarding table identifier for the namespace stored with a response's lease.

lease-namespace-vpn-id

blob, typically 7 bytes (read-only)

Virtual private network (VPN) identifier for the namespace stored with a response's lease.

lease-relay-agent-circuit-id

blob

Accesses and manipulates the relay agent circuit id data as stored with a response's lease. Requires the suboption number 1 as the first byte. Deprecated in favor of the lease-relay-agent-circuit-id-data item.

lease-relay-agent-circuit-id-data

blob (use instead of deprecated lease-relay-agent-circuit-id)

Accesses and manipulates the relay-agent-circuit-id-data as stored with a response's lease. Relevant only if the save-relay-agent-data DHCP server attribute is enabled.

lease-relay-agent-remote-id

blob

Accesses and manipulates the relay-agent-remote-id data as stored with a response's lease. Requires suboption number 2 as the first byte. Deprecated in favor of the lease-relay-agent-remote-id-data item.

lease-relay-agent-remote-id-data

blob (use instead of lease-relay-agent-remote-id item)

Accesses and manipulates the relay-agent-remote-id-data as stored with a response's lease. Relevant only if the save-relay-agent-data DHCP server attribute is enabled.

lease-relay-agent-server-id-
override-data

IP address

Accesses and manipulates the relay-agent-server-id-override-data as stored with a response's lease. Relevant only if the save-relay-agent-data DHCP server attribute is enabled.

lease-relay-agent-subnet-
selection-data

IP address

Accesses and manipulates the relay-agent-subnet-selection-data as stored with a response's lease. Relevant only if the save-relay-agent-data DHCP server attribute is enabled.

lease-relay-agent-vpn-id-data

blob

Accesses and manipulates the relay-agent-vpn-id data as stored with a response's lease. Relevant only if the save-relay-agent-data DHCP server attribute is enabled.

lease-reserved

int (read-only)

If set to 1, reports if the lease is reserved.

lease-start-time-of-state

int (read-only)

Time, in seconds since 1970, that this lease was first placed into its current state.

lease-state

string (read-only)

State of the lease, which can be available, offered, expired, leased, or unavailable.

mac-address

blob

If set to 1, the scope allows BOOTP. Written after a DNS operation completes.

namespace-description

string (read-only)

Description for the namespace.

namespace-id

int (read-only)

Namespace identifier.

namespace-name

string (read-only)

Name of the namespace.

namespace-vrf-name

string (read-only)

Virtual routing and forwarding table (VRF) identifier for the namespace.

namespace-vpn-id

blob, typically 7 bytes (read-only)

Virtual private network (VPN) identifier for the namespace.

ping-clients

int

If set to 1, performs a ping before offering a lease for this request. Read just before determining a client's lease acceptability.

reply-ipaddress

IP address

IP address to use when replying to the DHCP client. Read just after pre-packet-encode. If you change its value in a pre-packet-encode, the IP address you place in it should be for a system that can respond to ARP queries (unless it is a broadcast address). Even if unicast is enabled and the broadcast flag is not set in the DHCP request, the local ARP cache is not set with a mapping from a new reply-ipaddress in the pre-packet-encode to the MAC address in the DHCP request.

reply-port

int

Port to use when replying to the DHCP client. Read just after pre-packet encode.

reverse-name-in-dns

int

If equal to 1, the reverse name is in DNS. Read before initializing a DNS operation.

scope-allow-bootp

int

If set to 1, the scope allows BOOTP. Written after a DNS operation completes.

scope-allow-dhcp

int (read-only)

If set to 1, the scope allows DHCP.

scope-allow-dynamic-bootp

int (read-only)

If set to 1, the scope allows dynamic BOOTP.

scope-available-leases

int (read-only)

Number of available leases on the current scope.

scope-deactivated

int (read-only)

If set to 1, the scope is de-activated.

scope-dns-forward-server-address

IP address (read-only)

DNS server to use for the DNS forward address.

scope-dns-forward-zone-name

string (read-only)

Forward zone name configured in the scope.

scope-dns-number-of-host-bytes

int (read-only)

Number of host bytes used by the DHCP server code that handles DNS updates.

scope-dns-reverse-server-address

IP address (read-only)

DNS server to use for the DNS reverse address.

scope-dns-reverse-zone-name

string (read-only)

Reverse zone name configured in the scope.

scope-name

string (read-only)

Name of the scope that contains the lease that the DHCP server is processing.

scope-network-number

IP address (read-only)

Network number of the scope that contains the lease the DHCP server is processing.

scope-ping-clients

boolean (read-only)

If set to 1, the scope associated with the current lease was configured to support a ping operation prior to offering a lease.

scope-primary-network-number

IP address (read-only)

Network number of this scope's primary scope.

scope-primary-subnet-mask

IP address (read-only)

Subnet mask of this scope's primary scope.

scope-renew-only

int (read-only)

If set to 1, the scope is renew-only.

scope-renew-only-expire-time

int (read-only)

Absolute time, in seconds since January 1, 1970, at which a renew-only scope should cease to be renew-only.

scope-selection-tags

string (read-only)

Comma-separated string that contains the scope's selection criteria.

scope-send-ack-first

int (read-only)

If set to 1, the scope sends an ACK before performing the rest of the processing.

scope-subnet-mask

IP address (read-only)

Subnet mask of the scope that contains the lease the DHCP server is processing.

scope-update-dns-enabled

int (read-only)

If set to 1, the scope has update DNS enabled.

scope-update-dns-for-bootp

int (read-only)

If set to 1, the scope has update DNS enabled for BOOTP.

transaction-time

int (read-only)

Time, in seconds since 1970, that the request was decoded.


Extension Dictionary API

This section contains the dictionary method calls to use when accessing dictionaries from Tcl extensions and shared libraries.

Tcl Attribute Dictionary API

In an attribute dictionary, the keys are constrained to be the names of attributes as defined in the Network Registrar DHCP server configuration. The values are the string representation of the legal values for that particular attribute. For example, IP addresses are specified by the dotted-decimal string representation of the address, and enumerated values are specified by the name of the enumeration. This means that numbers are specified by the string representation of the number.

Attribute dictionaries are unusual in that they can contain more than one instance of a key. These instances are ordered, with the first instance at index zero. Some of the attribute dictionary methods allow an index to indicate a particular instance or position in the list of instances to be referenced.

For the Tcl API routine signature and command syntax, see the "Tcl Attribute Dictionary API" section.

Tcl Request and Response Dictionary Methods

Attribute dictionaries use commands with which you can change and access the values in the dictionaries. Table C-6 lists the commands to use with the request and response dictionaries. In this case, you can define the dict variable as request or response.

See the install-path/examples/dhcp/tcl/tclextension.tcl file for examples.

Table C-6 Tcl Request and Response Dictionary Methods 

Method
Syntax

get

$dict get attribute [index [bMore]]

Returns the value of the attribute from the dictionary, represented as a string. If the dictionary does not contain the attribute, the empty string is returned instead. If you include the index value, this returns the indexth instance of the attribute. Some attributes can appear more than once in the request or response packet. The index selects which instance to return.

If you include the bMore, the get method sets bMore to TRUE if there are more attributes after the one returned, otherwise to FALSE. Use this to determine whether to make another call to get to retrieve other instances of the attribute.

log

$dict log level message ...

Outputs a message into the DHCP server's logging system. The level should be LOG_ERROR, LOG_WARNING, or LOG_INFO. The remaining arguments are concatenated and sent to the logging system at the specified level.

remove

$dict remove attribute [index]

Removes the attribute from the dictionary. If you omit the index or set it to the special value REMOVE_ALL, this removes any existing instances of the attribute. If you include the index as a number, this removes the instance of the attribute at the position indicated. This method always returns 1, even if the dictionary does not contain that attribute at that index.

put

$dict put attribute value [index]

Associates a value with the attribute in the dictionary. If you omit the index or set it to the special value REPLACE, this replaces any existing instances of the attribute with the single value. If you include the index value as the special value APPEND, this appends a new instance of the attribute to the end of the list of instances of the attribute. If you include the index value as a number, this inserts a new instance of the attribute at the position indicated. If you set the index value to the special value AUGMENT, this puts the attribute only if there is not one already.

trace

$dict trace level message ...

Returns a message in the DHCP server's packet tracing system. At level 0, no tracing occurs. At level 1, it traces only that the server received the packet and sent a reply. At level 4, it traces everything. The remaining arguments are concatenated and sent to the tracing system at the specified level. The default tracing is set using the DHCP server extension-trace-level attribute.


Tcl Environment Dictionary Methods

Table C-7 describes the commands to use with the environment dictionary. In this case, you can define the dict variable as environ, as in the following procedure example:

proc tclhelloworld2 { request response environ } { 
$environ put trace-level 4 
$environ log LOG_INFO "Environment hello world" 
} 

Table C-7 Tcl Environment Dictionary Methods 

Method
Syntax

clear

$dict clear

Removes all entries from the dictionary.

containsKey

$dict containsKey key

Returns 1 if the dictionary contains the key, otherwise 0.

firstKey

$dict firstKey

Returns the name of the first key in the dictionary. Note that the keys are not stored sorted by name. If a key does not exist, returns the empty string.

get

$dict get key

Returns the value of the key from the dictionary. If a key does not exist, returns the empty string.

isEmpty

$dict isEmpty

Returns 1 if the dictionary has no entries, otherwise 0.

log

$dict log level message ...

Returns a message in the DHCP server's logging system. The level should be one of LOG_ERROR, LOG_WARNING, or LOG_INFO. The remaining arguments are concatenated and sent to the logging system at the specified level.

nextKey

$dict nextKey

Returns the name of the next key in the dictionary that follows the key returned in the last call to firstKey or nextKey. If a key does not exist, returns the empty string.

put

$dict put key value

Associates a value with the key, replacing an existing instance of the key with the new value.

remove

$dict remove key

Removes the key from the dictionary. Always returns 1, even if the dictionary did not contain the key.

size

$dict size

Returns the number of entries in the dictionary.

trace

$dict trace level message ...

Returns a message in the DHCP server's packet tracing system. At level 0, no tracing occurs. At level 1, it traces only that the server received the packet and sent a reply. At level 4, it traces everything. The remaining arguments are concatenated and sent to the tracing system at the specified level. The default tracing is set using the DHCP server extension-trace-level attribute.


DEX Attribute Dictionary API

When writing DEX extensions for C/C++, you can specify keys as the attribute name's string representation or by type (a byte sequence defining the attribute). This mean that some of these access methods have four different variations that are the combinations of string or type for the key or value.

A basic DEX extension example might be:

int DEXAPI dexhelloworld( int iExtensionPoint, 
dex_AttributeDictionary_t* pRequest, 
dex_AttributeDictionary_t* pResponse, 
dex_EnvironmentDictionary_t* pEnviron ) 
{ 
pEnviron->log( pEnviron, DEX_LOG_INFO, "hello world" ); 
return DEX_OK; 
} 

See the install-path/examples/dhcp/dex/dexextension.c file or other files in that directory for examples.

DEX Request and Response Dictionary Methods

DEX attribute dictionaries use active commands, called methods, with which you can change and access values. Table C-8 lists the methods to use with the request and response dictionaries. In this case, you can define the pDict variable as pRequest or pResponse, as in:

pRequest->get( pRequest, "host-name", 0, 0 ); 

Table C-8 DEX Request and Response Dictionary Methods 

Method
Syntax

allocateMemory

void* pDict->allocateMemory( dex_AttributeDictionary_t* pDict, unsigned int iSize )

Allocates memory in extensions that persists only for the lifetime of this request.

get

const char* pDict->get( dex_AttributeDictionary_t* pDict, const char* pszAttribute, int iIndex, abool_t* pbMore )

Returns the value of the iIndexed instance of the attribute from the dictionary, represented as a string. If the dictionary does not contain the attribute (or that many instances of it), the empty string is returned instead. If pbMore is nonzero, the get method sets pbMore to TRUE if there are more instances of the attribute after the one returned, otherwise to FALSE. Use this to determine whether to make another call to get to retrieve other instances of the attribute.

getBytes

const abytes_t* pDict->getBytes( dex_AttributeDictionary_t* pDict, const char* pszAttribute, int iIndex, abool_t* pbMore )

Returns the value of the iIndexed instance of the attribute from the dictionary, as a sequence of bytes. If the dictionary does not contain the attribute (or that many instances of it), returns 0 instead. If pbMore is nonzero, the getBytes method sets it to TRUE if there are more instances of the attribute after the one returned, otherwise to FALSE. Use this to determine whether to make another call to getBytes to retrieve other instances of the attribute.

getByType

const char* pDict->getByType( dex_AttributeDictionary_t* pDict, const abytes_t* pszAttribute, int iIndex, abool_t* pbMore )

Returns the value of the iIndexed instance of the attribute from the dictionary, represented as a string. If the dictionary does not contain the attribute (or that many instances of it), returns the empty string instead. If pbMore is nonzero, the getByType method sets pbMore to TRUE if there are more instances of the attribute after the one returned, otherwise to FALSE. Use this to determine whether to make another call to getByType to retrieve other instances.

getBytesByType

const abytes_t* pDict-> getBytesByType( dex_AttributeDictionary_t* pDict, const abytes_t* pszAttribute, int iIndex, abool_t* pbMore )

Returns the value of the iIndexed instance of the attribute from the dictionary, as a sequence of bytes. If the dictionary does not contain the attribute (or that many instances of it), 0 is returned instead. If pbMore is nonzero, sets the variable pointed to TRUE if there are more instances of the attribute after the one returned, otherwise to FALSE. Use this to determine whether to make another call to get to retrieve other instances of the attribute.

getType

const abytes_t* pDict->getType( dex_AttributeDictionary_t* pDict, const char* pszAttribute )

Returns a pointer to the byte sequence defining the attribute, if the attribute name matches a configured attribute, otherwise 0.

log

abool_t pDict->log( dex_AttributeDictionary_t* pDict, int eLevel, const char* pszFormat, ... )

Returns a message in the DHCP server's logging system. The eLevel should be one of DEX_LOG_ERROR, DEX_LOG_WARNING, or DEX_LOG_INFO. The pszFormat is treated as a printf style format string, and it, along with the remaining arguments, are formatted and sent to the logging system at the specified level.

put

abool_t pDict->put( dex_AttributeDictionary_t* pDict, const char* pszAttribute, const char* pszValue, int iIndex )

Converts pszValue to a sequence of bytes, according to the definition of pszAttribute in the server configuration. Associates that sequence of bytes with the attribute in the dictionary. If iIndex is the special value DEX_REPLACE, replaces any existing instances of the attribute with a single value. If the special value DEX_APPEND, it appends a new instance of the attribute to its list. If the special value DEX_AUGMENT, puts the attribute only if there is not one already. Otherwise, inserts a new instance at the position indicated. Returns TRUE unless the attribute name does not match any configured attributes or the value could not be converted to a legal value.

putByType

abool_t pDict->putByType( dex_AttributeDictionary_t* pDict, const abytes_t* pszAttribute, const char* pszValue, int iIndex )

Converts pszValue to a sequence of bytes, according to the definition of pszAttribute in the server configuration. Associates that sequence of bytes with the attribute in the dictionary. If iIndex is the special value DEX_REPLACE, replaces any existing instances of the attribute with a single new value. If the special value DEX_APPEND, appends a new instance of the attribute to its list. If the special value DEX_AUGMENT, puts the attribute only if there is not one already. Otherwise, inserts a new instance at the position indicated.

putBytes

abool_t pDict->putBytes( dex_AttributeDictionary_t* pDict, const char* pszAttribute, const abytes_t* pszValue, int iIndex )

Associates pszValue with the pszAttribute in the dictionary. If iIndex is the special value DEX_REPLACE, replaces any existing instances of the attribute with a single new value. If the special value DEX_APPEND, appends a new instance of the attribute to its list. If the special value DEX_AUGMENT, puts the attribute only if there is not one already. Otherwise, inserts a new instance at the position indicated. Returns TRUE unless the attribute name does not match a configured one.

putBytesByType

abool_t pDict->putBytesByType( dex_AttributeDictionary_t* pDict, const abytes_t* pszAttribute, const abytes_t* pszValue, int iIndex )

Associates pszValue with the pszAttribute in the dictionary. If iIndex is the special value DEX_REPLACE, replaces any existing instances of the attribute with the new value. If the special value DEX_APPEND, appends a new instance of the attribute to its list. If the special value DEX_AUGMENT, puts the attribute only if there is not one already. Otherwise, inserts a new instance of the attribute at the position indicated.

remove

abool_t pDict->remove( dex_AttributeDictionary_t* pDict, const char* pszAttribute, int iIndex )

Removes the attribute from the dictionary. If iIndex is the special value DEX_REMOVE_ALL, removes any existing instances of the attribute. Otherwise, removes the instance at the position indicated. Returns TRUE, even if the dictionary did not contain that attribute at that index, unless the attribute name does not match any configured one.

removeByType

abool_t pDict->removeByType( dex_AttributeDictionary_t* pDict, const abytes_t* pszAttribute, int iIndex )

Removes the attribute from the dictionary. If iIndex is the value DEX_REMOVE_ALL, removes any existing instances of the attribute. Otherwise, removes the instance at the position indicated. Always returns TRUE, even if the dictionary does not contain that attribute at that index.

trace

abool_t pDict->trace( dex_AttributeDictionary_t* pDict, int iLevel, const char* pszFormat, ... )

Returns a message in the DHCP server's packet tracing system. At level 0, no tracing occurs. At level 1, it traces only that the server received the packet and sent a reply. At level 4, it traces everything. The remaining arguments are concatenated and sent to the tracing system at the specified level. The default tracing is set using the DHCP server extension-trace-level attribute.


DEX Environment Dictionary Methods

The environment dictionary uses active commands, called methods, with which you can change and access the dictionary values. Table C-9 lists the methods to use with the environment dictionary. In this case, you can define the pDict variable as pEnviron, as in:

pEnviron->log( pEnviron, DEX_LOG_INFO, "Environment hello world" ); 

Table C-9 DEX Environment Dictionary Methods 

Method
Syntax

allocateMemory

void* pDict->allocateMemory( dex_EnvironmentDictionary_t* pDict, unsigned int iSize )

Allocates memory for extensions that persists only for the lifetime of this request.

clear

void pDict->clear( dex_EnvironmentDictionary_t* pDict )

Removes all entries from the dictionary.

containsKey

abool_t pDict->containsKey( dex_EnvironmentDictionary_t* pDict, const char* pszKey )

Returns TRUE if the dictionary contains the key, otherwise FALSE.

firstKey

const char* pDict->firstKey( dex_EnvironmentDictionary_t* pDict )

Returns the name of the first key in the dictionary. Note that the keys are not stored sorted by name. If a key does not exist, returns the empty string.

get

const char* pDict->get( dex_EnvironmentDictionary_t* pDict, const char* pszKey )

Returns the value of the key from the dictionary. If a key does not exist, returns the empty string.

isEmpty

abool_t pDict->isEmpty( dex_EnvironmentDictionary_t* pDict )

Returns TRUE if the dictionary has 0 entries, otherwise FALSE.

log

abool_t pDict->log( dex_EnvironmentDictionary_t* pDict, int eLevel, const char* pszFormat, ... )

Returns a message in the DHCP server's logging system. The eLevel should be one of LOG_ERROR, LOG_WARNING, or LOG_INFO. The pszFormat is treated as a printf style format string, and it, along with the remaining arguments, are formatted and sent to the logging system at the specified level.

nextKey

const char* pDict->nextKey( dex_EnvironmentDictionary_t* pDict )

Returns the name of the next key in the dictionary that follows the key returned in the last call to firstKey or nextKey. If a key does not exist, returns the empty string.

put

abool_t pDict->put( dex_EnvironmentDictionary_t* pDict, const char* pszKey, const char* pszValue )

Associates a value with the key, replacing an existing instance of the key with the new value.

remove

abool_t pDict->remove( dex_EnvironmentDictionary_t* pDict, const char* pszKey )

Removes the key and the associated value from the dictionary. Always returns TRUE, even if the dictionary did not contain the key.

size

int pDict->size( dex_EnvironmentDictionary_t* pDict )

Returns the number of entries in the dictionary.

trace

abool_t pDict->trace( dex_EnvironmentDictionary_t* pDict, int iLevel, const char* pszFormat, ... )

Returns a message in the DHCP server's packet tracing system. At level 0, no tracing occurs. At level 1, it traces only that the server received the packet and sent a reply. At level 4, it traces everything. The remaining arguments are concatenated and sent to the tracing system at the specified level. The default tracing is set using the DHCP server extension-trace-level attribute.