[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 System Management Guide: Communications and Networks

TCP/IP Address and Parameter Assignment - Dynamic Host Configuration Protocol (DHCP)

Transmission Control Protocol/Internet Protocol (TCP/IP) enables communication between machines with configured addresses. Part of the burden a network administrator must face is address assignment and parameter distribution for all machines on the network. Commonly, this is a process in which the administrator dictates the configuration to each user, allowing the user to configure his own machine. However, misconfigurations and misunderstandings can generate service calls that the administrator must deal with individually. The Dynamic Host Configuration Protocol (DHCP) gives the network administrator a method to remove the end user from this configuration problem and maintain the network configuration in a centralized location.

DHCP is an application-layer protocol that allows a machine on the network, called a client, to get an IP address and other configuration parameters from the server. It gets information by exchanging packets between a daemon on the client and another on the server. Most operating systems now provide a DHCP client in their base package.

To obtain an address, the DHCP client daemon (dhcpcd on AIX) broadcasts a DHCP discover message, which is received by the server and processed. (Multiple servers can be configured on the network for redundancy.) If there is an address available for that client, a DHCP offer message is created, which contains an IP address and other options that are appropriate for that client. The client receives the DHCP offer and stores it while waiting for other offers. When the client chooses the best offer, it broadcasts a DHCP request that specifies which server's offer it wants.

All configured DHCP servers receive the request. Each checks to see if it is the requested server. If not, the server frees the address assigned to that client. The requested server marks the address as assigned and returns a DHCP acknowledgement, at which time, the transaction is complete and the client has an address for a period of time (lease) described by the server.

When half of the lease time is used, the client sends the server a renew packet to extend the lease time. If the server is willing to renew, it sends a DHCP acknowledgement. If the client does not get a response from the server that owns its current address, it broadcasts a DHCP rebind packet to reach the server if, for example, the server has been moved from one network to another. If the client has not renewed its address after the full lease time, the interface is brought down and the process starts over. This cycle prevents multiple clients on a network from being assigned the same address.

The DHCP server assigns addresses based on keys. Four common keys are network, class, vendor, and client ID. The server uses these keys to get an address and a set of configuration options to return to the client.

network
Identifies which network segment the packet came from. The network key allows the server to check its address database and assign an address by network segment.
class
Is completely client configurable. It can specify an address and options. This key could be used to denote machine function in the network or describe how machines are grouped for administrative purposes. For example, the network administrator might want to create a netbios class that contains options for NetBIOS clients or an accounting class that represents Accounting department machines that need access to a specific printer.
vendor
Helps identify the client by its hardware/software platform (for example, a Windows 95 client or an OS/2 Warp client).
client ID
Identifies the client either through the machine's host name or its medium access control (MAC) layer address. The client ID is specified in the configuration file of the dhcpcd daemon. Also, the client ID can be used by the server to pass options to a specific client or prohibit a particular client from receiving any parameters.

These keys can be used by the configuration either singularly or in combinations. If multiple keys are provided by the client and multiple addresses can be assigned, only one is chosen, and the option set is derived from the chosen key first. For more detailed information about the selection of keys and addresses, see Configuring DHCP.

The other piece of the picture is a BOOTP relay agent. A relay agent is needed so initial broadcasts from the client can leave the local network. The relay agents act as forwarding agents for DHCP and BOOTP packets.

The DHCP Server

For AIX version 4.3.1, the DHCP server has been segmented into three main pieces, a database, a protocol engine, and a set of service threads, each with its own configuration information.

The DHCP Database

The db_file.dhcpo database is used to track clients and addresses and for access control (for example, allowing certain clients on some networks but not others or disabling BOOTP clients on a particular network). Options are also stored in the database for retrieval and delivery to clients. The database is implemented as a dynamically loadable object, which allows for easy server upgrade and maintenance.

Using the information in the configuration file, the database is primed and verified for consistency. A set of checkpoint files handles updates to the database and reduces the overhead of writes to the main storage file. The database also contains the address and option pools, but these are static and are discussed in Configuring DHCP.

The main storage file and its back up are flat ASCII files that can be edited, if necessary. The format for the database main storage files are:

DF01 
"CLIENT ID" "0.0.0.0" State LeaseTimeStart LeaseTimeDuration LeaseTimeEnd 
  "Server IP Address" "Class ID" "Vendor ID" "Hostname" "Domain Name" 
"CLIENT ID" "0.0.0.0" State LeaseTimeStart LeaseTimeDuration LeaseTimeEnd 
  "Server IP Address" "Class ID" "Vendor ID" "Host Name" "Domain Name" 
...

The first line is a version identifier for the file: DF01c. The lines that follow are client record definition lines. The server reads from the second line to the end of the file. (The parameters in quotes must be enclosed in quotes.)

"CLIENT ID"
The ID the client uses to represent itself to the server.
"0.0.0.0"
is the IP address currently assigned to the DHCP server. If no address has been assigned, it will be "0.0.0.0".
State
The current state of the client. The DHCP protocol engine contains the allowable set, and the states are maintained in the DHCP database. The number next to State represents its value. The states can be:
(1) FREE
Represents addresses that are available for use. In general, clients do not have this state unless they have no address assigned. dadmin and the output from lssrc report this state as "Free".
(2) RESERVED
Indicates client and address are tied, but loosely. The client has issued a DHCP discover message and the DHCP server has responded, but the client has not yet responded with a DHCP request for that address. dadmin and the output from lssrc report this state as "Reserved".
(3) BOUND
Indicates client and address are tied and that the client has been assigned this address for some amount of time. dadmin and the output from lssrc report this state as "Leased".
(4) RELEASED
Indicates the client and address are tied for informational purposes only. The DHCP protocol suggests that DHCP servers maintain information about the clients it has served for future reference (mainly to try giving the same address to that client that has been assigned that address in the past). This state indicates that the client has released the address. The address is available for use by other clients, if no other addresses are available. dadmin and the output from lssrc report this as "Released".
(5) EXPIRED
Indicates the client and address are tied together, but only for informational purposes, in a similar manner to released addresses. The expired state, however, represents clients that let their leases expire. An expired address is available for use and is reassigned after all free addresses are unavailable and before released addresses are reassigned. dadmin and the output from lssrc report this state as "Expired".
(6) BAD
Represents an address that is in use in the network but has not been handed out by the DHCP server. This state also represents addresses that clients have rejected. Clients should not have this state. dadmin and the output from lssrc report this state as "Used" and "Bad", respectively.

The one state not listed above is UNKNOWN (value 0), which represents clients that have no address assigned. This state should never apply to addresses. dadmin reports "Unknown" and lssrc reports "Corrupt" for this state.

LeaseTimeStart
Is the start of the current lease time (in the number of seconds since January 1, 1970).
LeaseTimeDuration
Represents the duration of the lease (in seconds).
LeaseTimeEnd
Uses the same format as LeaseTimeStart, but it represents the end of the lease. Some configuration options use different values for the start and end of a lease and these values can be overridden by configuration file options. See DHCP Server File Syntax for db_file Database.
"Server IP Address"
Is the IP address of the DHCP server that owns this record.
"Class ID"
"Vendor ID"
"Host Name"
"Domain Name"
Are values that the server uses to determine which options are sent to the server (stored as quoted strings). These parameters increase performance, since option lists can be pregenerated for these clients when the DHCP server starts up.
Checkpoint Files

The syntax for the checkpoint files is not specified. If the server crashes or you have to kill it and cannot do a normal closing of the database, the server can process the checkpoint and backup files to reconstruct a valid database. The worst case could be to lose one client (the client that was being written to the checkpoint file when it crashed). The default files are:

/etc/db_file.cr
normal database operation
/etc/db_file.crbk
backups for the database
/etc/db_file.chkpt and /etc/db_file.ochkpt
rotating checkpoint files

The DHCP server for AIX Versions 4.3.1 and later is threaded. To maintain high throughput, database operations (including save operations) are thread efficient. When a save is in requested, the existing checkpoint file is rotated to the next checkpoint file, the existing database file is copied to the backup file, and the new save file is created. Each client record is then logged and a bit is toggled to indicate that the client should use the new checkpoint file for logging. When all client records are recorded, the save is closed, and the backup and old checkpoint files are deleted. This way, clients can still be processed and, depending on whether the client's record has been saved, database changes will go into a new save file or to a new checkpoint file.

The DHCP Protocol Engine

For AIX Versions 4.3.1 and later, the DHCP protocol engine has been updated to RFC 2131, but is still compatible with RFC 1541. (The server can also process options as defined in RFC 2132.) The protocol engine uses the database to determine what information should be returned to the client.

The configuration of the address pools have some configuration options that affect the state machine. For example, the DHCP server pings addresses before it hands them out. The amount of time the server waits for a response is now configurable for each address pool.

DHCP Threaded Operations

The last piece of the DHCP server is actually a set of operations that are used to keep things running. Since the DHCP server is threaded, these operations are actually set up as threads that occasionally do things to make sure everything is together.

The first thread, the main thread, handles the SRC requests (such as startsrc, stopsrc, lssrc, traceon, and refresh). This thread also coordinates all operations that affect all threads and handles signals. For example,

The next thread, the dadmin thread, interfaces with dadmin client program and the DHCP server. The dadmin tool can be used to get status as well as modify the database to avoid editing the database files manually. Previous versions of the DHCP server prevented any clients from getting addresses if a status request was running. With the addition of the dadmin and src threads, the server can handle service requests and still handle client requests.

The next thread is the garbage thread, which runs timers that periodically clean the database, save the database, purge clients that do not have addresses, and remove reserved addresses that have been in reserve state for too long. All these timers are configurable (see Configuring DHCP). The other threads are packet processors. The number of these is configurable; the default is 10. Each of these can handle a request from a DHCP client. The number of packet processors required is somewhat load- and machine-dependent. If the machine is used for other services than DHCP, it may not be wise to start up 500 threads.

Planning DHCP

To use this protocol, the network administrator needs to set up a DHCP server and configure BOOTP relay agents on links that do not have a DHCP server. Advance planning can reduce DHCP load on the network. For example, one server can be configured to handle all your clients, but all packets must be passed through it. If you have a single router between two large networks, it may be wiser to place two servers in your network, one on each link.

Another aspect to consider is that DHCP implies a pattern of traffic. For example, if you set your default lease time to fewer than two days and your machines are powered off for the weekend, Monday morning will be a period of high DHCP traffic. Although DHCP traffic does not cause huge overhead for the network, it needs to be considered when deciding where to place DHCP servers on a network and how many to use.

The goal of DHCP is that, after enabling DHCP to get the client on the network, a client has no requirement to enter anything. The DHCP client, dhcpcd, reads the dhcpcd.ini file, which contains information on logging and other parameters needed to start running. After installation, you need to decide which method to use for TCP/IP configuration: minimum configuration or DHCP. If DHCP is selected, you must choose an interface and you can specify some optional parameters. To choose the interface, you can select the keyword any, which tells dhcpcd to find the first interface that works and use it. This method minimizes the amount of input on the client side.

Configuring DHCP

By default, the DHCP server is configured by reading the /etc/dhcpsd.cnf file, which specifies the server's initial database of options and addresses. The server is started in the /etc/rc.tcpip file, or it can be started from Web-based System Manager, from SMIT, or through SRC commands. The DHCP client can be configured by running Web-based System Manager, the System Management Interface Tool (SMIT), or editing a flat ASCII file.

Configuring the DHCP server is usually the hardest part of using DHCP in your network. First, figure out what networks you need to have DHCP clients on. Each subnet in your network represents a pool of addresses that the DHCP server must add to its database. For example:

database db_file 
{ 
 
    subnet 9.3.149.0 255.255.255.0 
      {  option 3 9.3.149.1 # The default gateway clients on this network should use
         option 6 9.3.149.2 # The nameserver clients on this network should use 
      }  
    ... options or other containers added later 
}

The example above shows a subnet, 9.3.149.0, with a subnet mask 255.255.255.0. All addresses in this subnet, 9.3.149.1 through 9.3.149.254, are in the pool. Optionally, a range can be specified on the end of the line or a range or exclude statement can be included in the subnet container. See DHCP Server File Known Options for common configuration methods and definitions.

The database clause with db_file indicates which database method to use for processing this part of the configuration file. Comments begin with a # (pound sign). From the # to the end of the line are ignored by the DHCP server. Each option line is used by the server to tell the client what to do. DHCP Server File Known Options describes the currently supported and known options. See DHCP Server File Syntax for General Server Operation for ways to specify options that the server does not know about.

If the server does not understand how to parse an option, it uses default methods to send the option to the client. This also allows the DHCP server to send site-specific options that are not RFC defined, but may be used be certain clients or client configurations.

The Configuration File

The configuration file has an address section and an option definition section, which are based on the concept of containers that hold options, modifiers, and, potentially, other containers.

A container (basically, a method to group options) uses an identifier to classify clients into groups. The container types are subnet, class, vendor, and client. Currently, there is not a generic user-definable container. The identifier uniquely defines the client so that the client can be tracked if, for example, it moves between subnets. More than one container type may be used to define client access.

Options are identifiers that are returned to the client, such as default gateway and DNS address.

Modifiers are single statements that modify some aspect of a container, such as lease time default.

Containers

When the DHCP server receives a request, the packet is parsed and identifying keys determine which containers, options, and addresses are extracted.

The previous example shows a subnet container. Its identifying key is the client's position in the network. If the client is from that network, then it falls into that container.

Each type of container uses a different option to identify a client:

Except for subnets, each container allows the specification of the value that it will match including regular expression matching.

There is also an implicit container, the global container. Options and modifiers placed in the global container apply to all containers unless overridden or denied. Most containers can be placed inside other containers implying a scope of visibility. Containers may or may not have address ranges associated with them. Subnets, by their nature, have ranges associated with them.

The basic rules for containers and subcontainers are as follows:

Given the above rules, you can generate a hierarchy of containers that segment your options into groups for specific clients or sets of clients.

If a client matches multiple containers, how are options and addresses handed out? The DHCP server receives messages, it passes the request to the database (db_file in this case), and a container list is generated. The list is presented in order of depth and priority. Priority is defined as an implicit hierarchy in the containers. Strict containers are higher priority than regular containers. Clients, classes, vendors, and finally subnets are sorted, in that order, and within container type by depth. This generates a list ordered by most specific to least specific. For example:

 
    Subnet 1
    --Class 1
    --Client 1
    Subnet 2
    --Class 1
    ----Vendor 1 
    ----Client 1 
    --Client 1 

The example shows two subnets, Subnet 1 and Subnet 2. There is one class name, Class 1, one vendor name, Vendor 1, and one client name, Client 1. Class 1 and Client 1 are defined in multiple places. Because they are in different containers, their names can be the same but values inside them may be different. If Client 1 sends a message to the DHCP server from Subnet 1 with Class 1 specified in its option list, the DHCP server would generate the following container path:

Subnet 1, Class 1, Client 1

The most specific container is listed last. To get an address, the list is examined in reverse hierarchy to find the first available address. Then, the list is examined in forward hierarchy to get the options. Options override previous values unless an option deny is present in the container. Also, since Class 1 and Client 1 are in Subnet 1, they are ordered according to the container priority. If the same client is in Subnet 2 and sends the same message, the container list generated is:

Subnet 2, Class 1, Client 1 (at the Subnet 2 level), Client 1 (at the Class 1 level)

Subnet 2 is listed first, then Class 1, then the Client 1 at the Subnet 2 level (because this client statement is only one level down in the hierarchy). The hierarchy implies that a client matching the first client statement is less specific than the client matching Client 1 of Class 1 within Subnet 2.

Priority selected by depth within the hierarchy is not superseded by the priority of the containers themselves. For example, if the same client issues the same message and specifies a vendor identifier, the container list is:

Subnet 2, Class 1, Vendor 1, Client 1 (at Subnet 2 level), Client 1 (at Class 1 level)

Container priority improves search performance because it follows a general concept that client containers are the most specific way to define one or more clients. The class container holds less specific addresses than a client container; vendor is even less specific; and subnet is the least specific.

Addresses and Address Ranges

Any container type may have associated addresses ranges; subnets must have. Each range within a container must be a subset of the parent container's range and must not overlap with other containers' ranges. For example, if a class is defined within a subnet and the class has a range, the range must be a subset of the subnet's range. Also, the range within that class container cannot overlap with any other ranges at its level.

Ranges can be expressed on the container line and modified by range and exclude statements to allow for disjoint address sets associated with a container. So, if you have the top ten addresses and the second ten addresses of a subnet available, the subnet could specify these addresses by range in the subnet clause to reduce both memory use and the chance of address collision with other clients not in the specified ranges.

Once an address has been selected, any subsequent container in the list that contains address ranges is removed from the list along with its children. The reason for this is that network-specific options in removed containers are not valid if an address is not used from within that container.

Options

After the list has been culled to determine addresses, a set of options is generated for the client. In this selection process, options overwrite previously selected options unless a deny is encountered, in which case, the denied option is removed from the list being sent to the client. This method allows inheritance from parent containers to reduce the amount of data that must be specified.

Modifiers

Modifiers are items that modify some aspect of a particular container, such as access or lease time. After defining the address and option pools, start thinking about the container modifiers. The most common are leasetimedefault, supportBootp, and supportUnlistedclients.

leasetimedefault
Defines the amount of time an address is to be leased to a client.
supportBootp
Defines whether the server should respond to BOOTP clients.
supportUnlistedclients
Indicates whether clients should be explicitly defined by a client statement to receive addresses. The value for supportUnlistedClients can be none, dhcp, bootp, or both. This allows for you to restrict access to bootp client and allow all DHCP clients to get addresses.

Other modifiers are listed in DHCP Server File Syntax for db_file Database.

Logging

After selecting modifiers, the next item to set up is logging. It has a clause like the database, but its keyword is logging. When starting up, it is advisable to turn logging to its highest level. As the configuration file is assured, set the logging levels to lower, more convenient levels. The logitem keyword turns on the logging level, removing logitem will turn off the level. Other keywords for logging allow the specification of the log filename, file size, and number of rotating log files.

Server-specific Options

The last set of parameters to tweak are server-specific options, which allow the user to control the number of packet processors, how often the garbage collection threads are run, etc.

For example, two server-specific options are:

reservedTime
Indicates how long an address should stay in reserved state after sending an OFFER to the DHCP client
reservedTimeInterval
Indicates how often the DHCP server should scan through the addresses to see if there are any that have been in the reserved state long than reservedTime.

These options are useful if you have several clients that broadcast DISCOVER messages, but either they do not broadcast their REQUEST message or their REQUEST message gets lost in the network. Using these parameters keeps addresses from being reserved for a noncompliant client.

Another particularly useful option is SaveInterval, which indicates how often saves should occur. All server-specific options are listed in DHCP Server File Syntax for General Server Operation with the logging keywords.

Customizing a Configuration File

Many system administrators deal with networks that include multiple client types; for example, a single network may include Windows 95 computers, AIX computers, OS/2 computers, Java OS clients, and IBM Thin Client machines. Each of these require unique vendor identifiers (the field used to identify the type of machine to the DHCP server). Java OS clients and Thin Client machines can require unique parameters such as bootfiles, and configuration options may need to be tailored specifically for them. But the Windows 95 computers would not handle Java-specific options well. So, machine-specific options can be encapsulated within vendor containers.

To take this example further, imagine a primary use for certain machines based on the type of user for those machines. For instance, the development staff may use the AIX clients for programming, the marketing staff may use the OS/2 clients, sales may use Java OS clients and IBM Thin Client machines, and accounting may use Windows 95 machines. Each of these user families could need different configuration options (different printers, nameservers, or default web servers, etc.). In this case, such options could be included in the vendor container, since each group uses a different machine type. But if the same machine type is used by multiple groups, placing the options within a subordinate class identifier would allow your marketing managers, for example, to use a specific set of printers that other employees could not access.

Note: The following fictional example represents part of a configuration file. Comments are preceded by a pound sign (#) and describe how each line defines the installation.
vendor "AIX_CLIENT"
{
# No specific options, handles things based on class
}

vendor "OS/2 Client"
{
# No specific options, handles things based on class
}

vendor "Windows 95"
{ option 44 9.3.150.3          # Default NetBIOS Nameserver
}

vendor "Java OS"
{ bootstrapserver 9.3.150.4    # Default TFTP server for the Java OS boxes 
  option 67 "javaos.bin"       # The bootfile of the Java OS box
}

vendor "IBM Thin Client"
{ bootstrapserver 9.3.150.5    # Default TFTP server for Thin Client boxes 
  option 67 "thinos.bin"       # Default bootfile for the Thin Client boxes
}

subnet 9.3.149.0 255.255.255.0
{ option 3 9.3.149.1           # The default gateway for the subnet 
  option 6 9.3.150.2           # This is the nameserver for the subnet
  class accounting 9.3.149.5-9.3.149.20 
  {    	  # The accounting class is limited to address range 9.3.149.5-9.3.149.20         
          # The printer for this group is also in this range, so it is excluded.                  
     exclude 9.3.149.15                  
     option 9 9.3.149.15       # The LPR server (print server)         
     vendor "Windows 95"         
     {                 
     option 9 deny              # This installation of Windows 95 does not support  
                                # this printer, so the option is denied.
     }
  }
 . . .
}

DHCP and the Dynamic Domain Name System (DDNS)

The DHCP server provides options to enable operation in a DDNS environment. To use DHCP in a DDNS environment, you must set and use a Dynamic Zone on a DNS server.

After the DDNS server is configured, you must decide if the DHCP server is going to do A record updates, PTR record updates, updates for both record types, or none at all. This decision depends on whether a client machine can do part or all of this work.

The DHCP server has a set of configuration keywords that allow you to specify a command to run when an update is required. These are:

updatedns
(Deprecated.) Represents the command to issue to do any type of update. It will be called for both the PTR and the A record update.
updatednsA
Specifies the command to update the A record.
updatednsP
Specifies the command to update the PTR record.

These keywords specify executable strings that the DHCP server executes when an update is required. The keyword strings must contain four %s (percent symbol, letter s). The first %s is the hostname; the second, the domain name; the third, the IP address; and the fourth, the lease time. These are used as the first four parameters for the AIX command, dhcpaction. The remaining two parameters for dhcpaction indicate the record to update (A, PTR, NONE, or BOTH) and whether NIM should be updated (NIM or NONIM). See DHCP and Network Installation Management (NIM) Interactions and Suggestions for more information about NIM and DHCP interaction. For example:

updatednsA "/usr/sbin/dhcpaction '%s' '%s' '%s' '%s' A NONIM" 
                    # This does the dhcpaction command only on the A record
updatednsP "/usr/sbin/dhcpaction '%s' '%s' '%s' '%s' PTR NONIM" 
                    # This does the command only on the PTR record
updatedns "/usr/sbin/dhcpaction '%s' '%s' '%s' '%s' BOTH NIM" 
                    # This does the command on both records and updates NIM

The DHCP server also has a set of keywords to remove the DNS entries when a lease is released or expires. The keywords are:

releasednsA
Removes the A record.
releasednsP
Removes the PTR record.
removedns
Removes both record types.

These keywords specify executable strings that the DHCP server executes when an address is released or expired. AIX provides a command, dhcpremove, that works similarly to dhcpaction, but only takes three parameters:

  1. The IP address, specified as a %s in the command string
  2. Which record to remove (A, PTR, NONE, or BOTH).
  3. Whether NIM should be updated (NIM or NONIM).
releasednsA "/usr/sbin/dhcpremove '%s' '%s' '%s' A NONIM" 
                     # This does the dhcpremove command only the A record
releasednsP "/usr/sbin/dhcpremove '%s' '%s' '%s' PTR NONIM" 
                     # This does the command only on the PTR record
removedns "/usr/sbin/dhcpremove '%s' '%s' '%s' BOTH NIM" 
                     # This does the command on both records and updates NIM

The dhcpaction and dhcpremove scripts do some parameter checking, then set up a call to nsupdate, which has been updated to work with the AIX and OS/2 DDNS servers. See the nsupdate command description for more information.

Also, administrator-defined policies have been added for hostname exchanges between the server and the clients. By default, the hostname that is returned to the client and used for a DDNS update is option 12 (defined in the server configuration file). Alternatively, the default hostname can be a the client suggested hostname, either through option 81 (the DHCPDDNS option) or through option 12 (the HOSTNAME option). However, the administrator can override the default hostname by using the hostnamepolicy, proxyarec, and appenddomain configuration keywords. These options and their parameters are defined in DHCP Server File Syntax for db_file Database.

DHCP Compatability with Older Versions

The DHCP server for AIX Versions 4.3.1 and later recognizes previous versions' configuration and database files, dhcps.ar and dhcps.cr. It parses the old configuration files and generates new database files in the old locations. The old databases are converted automatically to the new file. The configuration file itself is not converted.

The DHCP server database module, db_file, can read the old format. The DHCP server can recognize when a database container is not in the configuration file and treat the whole file as configuring the server parameters, logging parameters, and the db_file database parameters.

Notes: Some old configuration file syntax is deprecated, but is still supported. Other deprecations are:

DHCP Server File Known Options

Note: The options that are shown in the following table as not allowed to be specified, can be specified in the configuration file, but will be overwritten by the proper value. For a better definition of each option, see RFC 2132.
Option Number Default Data Type Can Specify? Description/Use
0 None No Pads out the option field, if necessary. The server adds padding when necessary.
1 Dotted quad No Net mask of the subnet from which the address was drawn.
2 32-bit integer Yes Specifies the offset of the client's subnet, in seconds from Coordinated Universal Time (UTC).
3 One or more dotted quads Yes A list of the default gateways' IP addresses.
4 One or more dotted quads Yes A list of time servers' IP addresses.
5 One or more dotted quads Yes A list of name servers' IP addresses.
6 One or more dotted quads Yes A list of DNS IP addresses.
7 One or more dotted quads Yes A list of log servers' IP addresses.
8 One or more dotted quads Yes A list of cookie servers' IP addresses.
9 One or more dotted quads Yes A list of LPR servers' IP addresses.
10 One or more dotted quads Yes A list of Impress servers' IP addresses.
11 One or more dotted quads Yes A list of Resource Location servers' IP addresses.
12 An ASCII string Yes A hostname for the client to use.
13 16-bit unsigned integer Yes Size of the bootfile.
14 An ASCII string Yes Path for Merit Dump file.
15 An ASCII string Yes The default DNS domain name.
16 An IP address Yes The address of the Swap server.
17 An ASCII string Yes The default root path.
18 An ASCII string Yes The path to extensions for the client.
19 Yes, No, True, False, 1, 0 Yes Whether IP Forwarding should be turned on.
20 Yes, No, True, False, 1, 0 Yes Whether non-local source routing should be used.
21 One or more pairs of dotted quads, in the form DottedQuad:DottedQuad Yes Filter policies for IP addresses.
22 16-bit unsigned integer Yes Maximum size to allow for datagram fragments.
23 8-bit unsigned integer Yes IP time-to-live (TTL).
24 32-bit unsigned integer Yes Number of seconds to use in the Path MTU aging timeout.
25 List of one or more 16-bit unsigned integers Yes Path MTU Plateau table. Specifies a set of values that represent the MTU sizes to use when using Path MTU discovery.
26 16-bit unsigned integer Yes MTU size for the receiving interface.
27 Yes, No, True, False, 1, 0 Yes Whether all subnets are local.
28 An IP address (dotted quad) Yes Broadcast address for the interface.
29 Yes, No, True, False, 1, 0 Yes Whether ICMP netmask discovery should be used.
30 Yes, No, True, False, 1, 0 Yes Whether client should become an ICMP netmask supplier.
31 Yes, No, True, False, 1, 0 Yes Whether ICMP Router Discovery messages should be used.
32 IP address (dotted quad) Yes Address to use for router solicitation.
33 One or more IP address pairs, in the form DottedQuad:DottedQuad Yes Each address pair represents a static route.
34 Yes/No, True/False, 1/0 Yes Whether trailer encapsulation should be used.
35 32-bit unsigned integer Yes ARP cache timeout value.
36 Yes/No, True/False, 1/0 Yes Whether Ethernet encapsulation should be used.
37 8-bit unsigned integer Yes TCP time-to-live (TTL).
38 32-bit unsigned integer Yes TCP keep alive interval.
39 Yes/No, True/False, 1/0 Yes Whether TCP keep alive should be used.
40 An ASCII string Yes The NIS default domain.
41 One or more dotted quads Yes The IP addresses of the NIS servers.
42 One or more dotted quads Yes The IP addresses of the NTP servers.
43 hex string of digits, in the form of hex "digits", hex "digits", or 0xdigits Yes, but really only specified with vendor container Encapsulated option container for the vendor container.
44 One or more dotted quads Yes NetBIOS name servers' IP addresses.
45 One or more dotted quads Yes NetBIOS datagram distribution servers' IP addresses.
46 8-bit unsigned integer Yes NetBIOS Node Type.
47 hex string of digits, in form of hex "digits", hex "digits", or 0xdigits Yes NetBIOS Scope.
48 One or more dotted quads Yes X Windows font servers' IP addresses.
49 One or more dotted quads Yes X Windows Display Manager.
50 None No Requested IP Address, used by client to indicate the address it wants.
51 32-bit unsigned integer Yes Lease time for the returned address. By default, the DHCP server uses the leasetimedefault keyword, but direct specification of option 51 overrides it.
52 None No Option overload. Client uses this to indicate the sname and file fields of the BOOTP packet may have options.
53 None No DHCP server or client uses this option to indicate the type of DHCP message.
54 None No DHCP server or client uses this option to indicate the server's address or the server to which the message is directed.
55 None No DHCP client uses this to indicate desired options.
56 An ASCII string Yes A string the DHCP server sends to the client. In general, this can be used by the DHCP server and client to indicate problems.
57 No No DHCP client uses this option to tell the DHCP server the maximum DHCP packet size the client can receive.
58 32-bit unsigned integer Yes The number of seconds until the client should send a renew packet.
59 32-bit unsigned integer Yes The number of seconds until the client should send a rebind packet.
60 None No DHCP client uses this option to indicate its vendor type. The DHCP server uses this field to match vendor containers.
61 None No DHCP client uses this to uniquely identify itself. The DHCP server uses this field to match client containers.
64 An ASCII string Yes Specifies the NIS+ domain.
65 One or more dotted quads Yes IP Addresses of NIS+ servers.
66 An ASCII string Yes Specifies the TFTP server name. This is a hostname and is used instead of the siaddr field if the client understands this option.
67 An ASCII string Yes Specifies the bootfile name. This can be used instead of the bootfile keyword, which places the file in the filename field of the packet.
68 One or more dotted quads, or NONE Yes Addresses of home agents.
69 One or more dotted quads Yes Default SMTP servers to use.
70 One or more dotted quads Yes Default POP3 servers to use.
71 One or more dotted quads Yes Default NNTP servers to use.
72 One or more dotted quads Yes Default WWW servers to use.
73 One or more dotted quads Yes Default Finger servers to use.
74 One or more dotted quads Yes Default IRC servers to use.
75 One or more dotted quads Yes Default Street Talk servers to use.
76 One or more dotted quads Yes Default Street Talk directory assistance servers to use.
77 An ASCII string Yes The user site class identifier. The DHCP server uses this field to match class containers.
81 An ASCII string plus other items No The DHCP client uses this option to define the policy the DHCP server should use with respect to DDNS.
255 None No DHCP server and client use this option to indicate the end of an option list.

DHCP Server File Syntax for General Server Operation

Note: Time Units (time_units) shown in the following table are optional and represent a modifier to the actual time. The default time unit is minutes. Valid values are seconds (1), minutes (60), hours (3600), days (86400), weeks (604800), months (2392000), and years (31536000). The number shown in parentheses is a multiplier applied to the specified value n to express the value in seconds.
Keyword Form Subcontainers? Default Value Meaning
database database db type Yes None The primary container that holds the definitions for the address pools, options, and client access statements. db type is the name of a module that is loaded to process this part of the file. The only value available to current AIX versions is db_file.
logging_info logging_info Yes None The primary logging container that defines the logging parameters.
logitem logitem NONE No All default to not enabled. Enables the logging level. Multiple lines are allowed.
logitem SYSERR
logitem OBJERR
logitem PROTOCOL
logitem PROTERR
logitem WARN
logitem WARNING
logitem CONFIG
logitem EVENT
logitem PARSEERR
logitem ACTION
logitem ACNTING
logitem STAT
logitem TRACE
logitem RTRACE
logitem START
numLogFiles numLogFiles n No 0 Specifies the number of log files to create. The log rotates when the first one fills. n is the number of files to create.
logFileSize logFileSize n No 0 Specifies the size of each log file in 1024-byte units.
logFileName logFileName path No None Specifies the path to the first log file. The original log file is named filename or filename.extension. The filename must be eight or fewer characters. When a file is rotated, it is renamed beginning with the base filename, then either appending a number or replacing the extension with a number. For example, if the original file name is file, the rotated file name becomes file01. If the original file name is file.log, it becomes file.01.
CharFlag charflag yes No true Not applicable to the AIX DHCP server, but the OS/2 DHCP server uses it to produce debug windows.
charflag true
charflag false
charflag no
StatisticSnapShot StatisticSnapShot n No -1, never Specifies how often statistics are written to the log file in seconds.
UsedIpAddressExpireInterval UsedIpAddressExpireInterval n time_units No -1, never Specifies how often addresses placed in the BAD state are recouped and retested for validity.
leaseExpireInterval leaseExpireInterval n time_units No 900 seconds Specifies how often addresses in the BOUND state are checked to see if they have expired. If the address has expired, the state is moved to EXPIRED.
reservedTime reservedTime n time_units No -1, never Specifies how long addresses should sit in RESERVED state before being recouped into the FREE state.
reservedTimeInterval reservedTimeInterval n time_units No 900 seconds Specifes how often addresses in the RESERVE state are checked to see if they should be recouped into the FREE state.
saveInterval saveInterval n time_units No 3600 seconds Specifies how often the DHCP server should force a save of the open databases. For heavily loaded servers, this should be 60 or 120 seconds.
clientpruneintv clientpruneintv n time_units No 3600 seconds Specifies how often the DHCP server has the databases remove clients are not associated with any address (in the UNKNOWN state). This reduces the memory use of the DHCP server.
numprocessors numprocessors n No 10 Specifies the number of packet processors to create. Minimum of one.

DHCP Server File Syntax for db_file Database

Notes: Time Units (time_units) shown in the following table are optional and represent a modifier to the actual time. The default time unit is minutes. Valid values are seconds (1), minutes (60), hours (3600), days (86400), weeks (604800), months (2392000), and years (31536000). The number shown in parentheses is a multiplier applied to the specified value n to express the value in seconds.

Also, items that are specified in one container can be overridden inside a subcontainer. For example, you could globally define BOOTP clients, but within a certain subnet allow BOOTP clients by specifying the supportBootp keywork in both containers.

The client, class, and vendor containers allow for regular expression support. For class and vendor, a quoted string with the first character after the quote being an exclamation point (!) indicates that the rest of the string should be treated as a regular expression. The client container allows for regular expressions on both the hwtype and the hwaddr fields. A single string is used to represent both fields with the following format:

decimal_number-data

If decimal_number is zero, then data is an ASCII string. If any other number, data is hex digits.

Keyword Form Subcontainers? Default Value Meaning
subnet subnet subnet id netmask Yes None Specifies a subnet and a pool of addresses. All addresses are assumed to be in the pool unless a range is specified on the line or addresses are modified later in the container by a range or exclude statement. The optional range is a pair of IP addresses in dotted quad format separated by a dash. An optional label and priority can be specified. These are used by virtual subnets to identify and order the subnets in the virtual subnet. The label and priority are separated by a colon. These containers are only allowed at the global or database container level.
subnet subnet id netmask range
subnet subnet id netmask label:priority
subnet subnet id netmask range label:priority
subnet subnet subnet id range Yes None Specifies a subnet that goes within a network container. It defines a range of addresses that is the whole subnet unless the optional range part is specified. The netmask associated with the subnet is taken from the surrounding network container.
Note: This method is deprecated in favor of the other subnet forms.
option option number data ... No None Specifies an option to send to a client or, in the case of deny, an option to prevent from being sent to the client. The option * deny clause means all options not specified in the current container are not to be returned to the client. option numberdeny only denies the specified option. number is an unsigned 8-bit integer. data is specific to the option (see above) or can be specified as a quoted string (indicating ASCII text) or 0xhexdigits or hex"hexdigits" or hex "hexdigits". If the option is in a vendor container, the option will be encapsulated with other options in an option 43.
option numberdeny
option * deny
exclude exclude an IP address No None Modifies the range on the container in which the exclude statement is in. The exclude statement is not valid in the global or database container levels. The exclude statement removes the specified address or range from the current range on the container. The exclude statement allows you to create non-contiguous ranges for subnets or other containers.
exclude dotted_quad-dotted_quad
range range IP_address No None Modifies the range on the container in which the range statement is in. The range statement is not valid in the global or database container levels. If the range is the first in the container that does not specify a range on the container definition line, then the range for the container becomes the range specified by the range statement. Any range statement after the first range or all range statements for a containers that specifies ranges in its definition are added to the current range. With the range statement, a single address or set of addresses can be added to the range. The range must fit inside the subnet container definition.
range dotted_quad-dotted_quad
client client hwtype hwaddr NONE Yes None Specifies a client container that denies the client specified by the hwaddr and hwtype from getting an address. If hwtype is 0, then hwaddr is an ASCII string. Otherwise, hwtype is the hardware type for the client and hwaddr is the hardware address of the client. If the hwaddr is a string, then quotes are accepted around the string. If the hwaddr is a hexstring, then the address may be specified by 0xhexdigits or hex digits. range allows the client specified by the hwaddr and hwtype to get an address in the range. Must be regular expressions to match multiple clients.
client hwtype hwaddr ANY
client hwtype hwaddr dotted_quad
client hwtype hwaddr range
class class string Yes None Specifies a class container with name string. String can be quoted or not. If quoted, the quotes are removed before comparison. Quotes are required for strings with spaces or tabs. This container is valid at any level. A range can be supplied to indicate a set of addresses to hand out to a client with this class. The range is either a single dotted quad IP address or two dotted quad IP addresses separated by a dash.
class string range
network network network id netmask Yes None Specifies a network ID using class information (for example, 9.3.149.0 with a netmask of 255.255.255.0 would be network 9.0.0.0 255.255.255.0). This version of the network container is used to hold subnets with the same network ID and netmask. When a range is provided, all the addresses in the range are in the pool. The range must be in the network ID's network. This uses class full addressing. This is only valid in the global or database container level.
Note: The network keyword is deprecated in favor of the subnet container.
network network id
network network id range
vendor vendor vendor_id Yes None Specifies a vendor container. Vendor containers are used to return option 43 to the client. The vendor id may be specified in a quoted string or a binary string in the form 0xhexdigits or hex"digits". An optional range may be placed after the vendor id. The range is specified as two dotted quads separated by a dash. After the optional range, an optional hexstring or ASCII string can be specified as the first part of the option 43. If options are in the container, they are appended to the option 43 data. After all options are processed an End Of Option List Option is appended to the data. To return options outside of an option 43, use a regular expression client that matches all clients to specify normal options to return based on the vendor ID.
vendor vendor_id hex""
vendor vendor_id hex ""
vendor vendor_id 0xdata
vendor vendor_id ""
vendor vendor_id range
vendor vendor_id range hex""
vendor vendor_id range hex ""
vendor vendor_id range 0xdata
vendor vendor_id range ""
virtual virtual fill id id ... No None Specifies a virtual subnet with a policy. fill means use all addresses in the container before going to the next container. rotate means select an address from the next pool in the list on each request. sfill and srotate are the same as fill and rotate, but a search is done to see if the client matches containers, vendors, or classes in the subnet. If a match is found that can supply an address, the address is taken from that container instead of following the policy. There can be as many IDs as needed. id is either the subnet ID from the subnet definition or the label from the subnet definition. The label is required if there are multiple subnets with the same subnet id.
virtual sfill id id ...
virtual rotate id id ...
virtual srotate id id ...
inorder: inorder: id id ... No None Specifies a virtual subnet with a policy of fill, which means use all addresses in the container before going to the next container. There can be as many IDs as needed. id is either the subnet ID from the subnet definition or the label from the subnet definition. The label is required if there are multiple subnets with the same subnet ID.
balance: balance: id id ... No None Specifies a virtual subnet with a policy of rotate, which means use the next address in the next container. There can be as many IDs as needed. id is either the subnet ID from the subnet definition or the label from the subnet definition. The label is required if there are multiple subnets with the same subnet ID.
supportBootp supportBootp true No Yes Specifies whether the current container and all below it (until overridden) should support BOOTP clients.
supportBootp 1
supportBootp yes
supportBootp false
supportBootp 0
supportBootp no
supportUnlistedclients supportUnlistedclients BOTH No Both Specifies whether the current container and all below it (until overridden) should support unlisted clients. The value indicates whether all clients should be allowed access without specific client statements, DHCP clients only, BOOTP clients only, or no one.
Note: The true and false values are supported for compatability with previous versions and are deprecated. The true value cooresponds to BOTH and the false value cooresponds to NONE.
supportUnlistedclients DHCP
supportUnlistedclients BOOTP
supportUnlistedclients NONE
supportUnlistedclients true
supportUnlistedclients yes
supportUnlistedclients 1
supportUnlistedclients false
supportUnlistedclients no
supportUnlistedclients 0
addressrecorddb addressrecrddb path No None If specified, it works like the backupfile keyword. Only valid in the global or database container level.
Note: This method is deprecated.
backupfile backupfile path No /etc/db_file.crbk Specifies the file to use for database backups. Only valid in the global or database container level.
checkpointfile checkpointfile path No /etc/db_file.chkpt Specifes the database checkpoint files. The first checkpoint file is the path. The second checkpoint file is path with the last character replaced with a 2. So, the checkpoint file should not end in 2. Only valid in the global or database container level.
clientrecorddb clientrecorddb path No /etc/db_file.cr Specifies the database save file. The file contains all the client records the DHCP server has serviced. Only valid in the global or database container level.
bootstrapserver bootstrapserver IP address No None Specifes the server clients should use from which to TFTP files after receiving BOOTP or DHCP packets. This value fills in the siaddr field in the packet. This is valid at any container level.
giaddrfield giaddrfield IP address No None Specifies the giaddrfield for response packets.
Note: This specification is illegal in the BOOTP and DHCP protocols, but some clients require the giaddr field to be the default gateway for the network. Because of this potential conflict, giaddrfield should only be used within a client container, although it can work at any level.
pingTime pingTime n time_unit No 3 seconds Specifies the amount of time to wait for a ping response before handing out an address. The default time unit is hundredths of a second. The time unit value is defined in the note preceding this table. This is valid at any container level. The time_unit parameter is optional.
bootptime bootptime n time_unit No -1, infinite Specifies the amount of time to lease an address to a BOOTP client. The default is -1, which means infinite. The normal time unit values are available. The time unit parameter is optional. This is valid at any container level.
AllRoutesBroadcast allroutesbroadcast no No 0 Specifies whether responses should be broadcast to all routes, if a broadcast response is required. This is valid at any container level. This is ignored by AIX DHCP servers, because the actual MAC address of the client, including RIFs, are stored for the return packet. This is valid at any container level.
allroutesbroadcast false
allroutesbroadcast 0
allroutesbroadcast yes
allroutesbroadcast true
allroutesbroadcast 1
addressassigned addressassigned "string" No None Specifies a quoted string to execute when an address is assigned to a client. The string should have two %s. The first %s is the client id in the form type-string. The second %s is an IP address in dotted quad format. This is valid at any container level.
addressreleased addressreleased "string" No None Specifes a quoted string to execute when an address is released by a client. The string should have one %s. The %s is the IP address being released in dotted quad format. This is valid at any container level.
appenddomain appenddomain 0 No No Specifies whether to append the defined option 15 domain name to the client-suggested hostname in the event that the client does not suggest a domain name as well. This is valid at any container level.
appenddomain no
appenddomain false
appenddomain 1
appenddomain yes
appenddomain true
canonical canonical 0 No 0 Specifies that the client id is in canonical format. This is valid only in the client container.
canonical no
canonical false
canonical 1
canonical yes
canonical true
leaseTimeDefault leaseTimeDefault n time_unit No 86400 seconds Specifies the default lease time for clients. This is valid at any container level. The time_unit parameter is optional.
proxyarec proxyarec never No usedhcpddnsplus Specifies what options and methods should be used for A record updates in the DNS. never means never update the A record. usedhcpddns means use option 81 if the client specifies it. usedhcpddnsplus means use option 81 or option 12 and 15, if specified. always means do the A record update for all clients. XXXXprotected modifies the nsupdate command to make sure the client is allowed. standard is a synonym for always. protected is a synonym for alwaysprotected. This is valid at any container level.
proxyarec usedhcpddns
proxyarec usedhcpddnsplus
proxyarec always
proxyarec usedhcpddnsprotected
proxyarec usedhcpddnsplusprotected
proxyarec alwaysprotected
proxyarec standard
proxyarec protected
releasednsA releasednsA "string" No None Specifies the execution string to use when an address is released. The string is used to remove the A record associated with the address released. This is valid at any container level.
releasednsP releasednsP "string" No None Specifies the execution string to use when an address is released. The string is used to remove the PTR record associated with the address released. This is valid at any container level.
removedns removedns "string" No None Specifies the execution string to use when an address is released. The string is used to remove the PTR and A record associated with the address released. This is valid at any container level.
Note: This is deprecated in favor of the releasednsA and releasednsP keywords.
updatedns updatedns "string" No None Specifies the execution string to use when an address is bound. The string is used to update both the A and the PTR record associated with the address. This is valid at any container level.
Note: This is deprecated in favor of the updatednsA and updatednsP keywords.
updatednsA updatednsA "string" No None Specifies the execution string to use when an address is bound. The string is used to update the A record associated with the address. This is valid at any container level.
updatednsP updatednsP "string" No None Specifies the execution string to use when an address is bound. The string is used to update the PTR record associated with the address. This is valid at any container level.
hostnamepolicy hostnamepolicy suggested No default Specifies which hostname to return to the client. Default policy is to prefer the defined hostname and domain name over suggested names. Other policies imply strict adherence (for example: defined will return the defined name or none if no name is defined in the configuration). Also, policies using the always modifier will dictate the server to return the hostname option regardless of whether the client requested it through the parameter list option. Note that suggesting a hostname also implies requesting it, and hostnames can be suggested through option 81 or through options 12 and 15. This keyword is valid at any container level.
hostnamepolicy resolved
hostnamepolicy always_resolved
hostnamepolicy defined
hostnamepolicy always_defined
hostnamepolicy default
bootfilepolicy bootfilepolicy suggested No suggested Specifies a preference for returning the bootfile name to a client. suggested prefers the client-suggested bootfile name to any server-configured name. merge appends the client suggested name to the server-configured home directory. defined prefers the defined name over any suggested bootfile name. dlways returns the defined name regardless of whether the client requests the bootfile option through the parameter list option.
bootfilepolicy merge
bootfilepolicy defined
bootfilepolicy always
stealfromchildren stealfromchildren true No No Specifies whether the parent container should "steal" from children containers when the parent container runs out of addresses. This means that if you have a subnet with class defined with a range of addresses, those addresses are reserved for those clients that specify that class. If stealfromchildren is true, then addresses will be pulled from a child to try and satisfy the request. The default is to not steal an address.
stealfromchildren 1
stealfromchildren yes
stealfromchildren false
stealfromchildren 0
stealfromchildren no
homedirectory homedirectory path No None Specifies the home directory to use in the file section of the response packet. This can be specified at any container level. The bootfile policy defines how items specified in the file section of the incoming packet interact with the bootfile and the home directory statements.
bootfile bootfile path No None Specifies the bootfile to use in the file section of the response packet. This can be specified at any container level. The bootfile policy defines how items specified in the file section of the incoming packet interact with the bootfile and the home directory statements.

DHCP and Network Installation Management (NIM) Interactions and Suggestions

The concept of dynamically assigning Internet Protocol (IP) addresses is fairly new. The following suggestions are provided to help with DHCP and NIM interaction.

  1. When configuring objects in the NIM environment, use host names whenever possible. This allows you to use a dynamic nameserver that updates the IP addresses when the host name is converted to an IP address in the NIM environment.

  2. You should place the NIM master and the DHCP server on the same system. The DHCP server has an option in the update DNS string that, when set to NIM, attempts to keep the NIM objects out of those states that need static IP addresses when those addresses change.

  3. For NIM clients, you should set the default lease time to twice the time it takes to install a client. This allows a leased IP address to be valid during the installation. After the installation, the client will reboot, and DHCP will be started or will need to be configured, depending on the type of installation.

  4. The dhcpsd server should be responsible for both the PTR and the A DNS records. When NIM reinstalls the machine, the file containing the RSA is deleted, and the client cannot update its records. Therefore, the server should update the system records. To do this, change the updatedns line in /etc/dhcpcd.ini to:
    updatedns "/usr/sbin/dhcpaction '%s' '%s' '%s' '%s' NONE NONIM"

    In the /etc/dhcpsd.cnf file, change the updatedns line to:

    updatedns "/usr/sbin/dhcpaction '%s' '%s' '%s' '%s' BOTH NIM"
    Note: When a NIM object is placed into the BOS installation pending state, the dhcpsd server may pass arguments that are different from those originally intended. To avoid this, try to minimize the time the client is in this pending state.

Following these suggestions should allow the NIM environment to work with dynamic clients.

For more information on Network Installation Management, see AIX Network Installation Management Guide and Reference.


[ Previous | Next | Contents | Glossary | Home | Search ]