omshell

omshell [options]

-s server
    Connects to the specified server (IP address or hostname). Default is localhost.

-p port
    Connects to the specified port on the server. Default is 7911.

-k key-file
    Specifies the path to a shared secret key-file for authentication. This file must contain a key declaration matching one configured in dhcpd.conf.

-r
    Opens the connection in read-only mode. No modifications can be made to the DHCP server's configuration.

-d
    Enables debug mode, providing more verbose output for troubleshooting.

-D
    Enables development mode, typically for internal use and more granular debugging.

-c
    Connects immediately upon startup without waiting for an explicit connect command.

-l lease-file
    Specifies an alternative DHCP lease database file to read. This is usually for debugging or inspection of a specific lease file.

-v
    Displays the version information of omshell.

-h
    Displays a brief help message and exits.

omshell is an interactive object management API (OMAPI) shell. It allows administrators to connect to and interact with the ISC DHCP server (dhcpd) using the OMAPI protocol. This shell provides a programmatic interface to inspect and modify the DHCP server's runtime configuration, including leases, host declarations, and other dynamic objects. It's particularly useful for automating tasks, debugging, or making on-the-fly changes to a running DHCP service without restarting it.

omshell communicates with dhcpd over a network socket, typically on a local host, and often requires shared secret authentication using a key file for security. It presents a command-line interface where users can issue OMAPI commands like connect, new, open, set, get, update, remove, and end to manipulate DHCP objects. This powerful tool provides granular control over the DHCP server's operational state.

• omshell requires the ISC DHCP server (dhcpd) to be running and configured to accept OMAPI connections. The omapi-port and key declarations must be present in dhcpd.conf.


• Authentication using a shared secret key-file is crucial for security. Without proper keys, connection might be denied or insecure.


• Modifications made through omshell directly affect the running dhcpd instance. Care should be taken as incorrect commands can disrupt DHCP services.


• It's a specialized tool for DHCP management, not a general-purpose network utility. Its syntax and commands are specific to OMAPI.

The Object Management API (OMAPI) is a simple, extensible protocol used by ISC DHCP software to manipulate and query objects. omshell leverages this protocol to send commands and receive responses from the DHCP server. OMAPI objects can represent leases, hosts, subnets, and other DHCP-related entities. Commands within omshell (e.g., new lease, open host, set ip-address, update) directly map to OMAPI operations.

Due to its ability to modify the running DHCP server, omshell connections are typically secured using shared secret keys. These keys are defined in dhcpd.conf and referenced by omshell via the -k option. It's critical to protect these key files and restrict omshell access to authorized administrators, as unauthorized access could lead to network disruption or IP address conflicts.

Once connected, omshell supports various commands for object manipulation:
connect: Establishes a connection to the DHCP server.
new : Creates a new object in memory (e.g., new lease).
open : Opens an existing object for manipulation (e.g., open lease).
set = : Sets an attribute of the currently active object.
get : Retrieves the value of an attribute.
update: Applies changes to the object on the server.
remove: Deletes the object from the server.
list: Lists available objects/attributes (context-dependent).
end: Closes the current object or session.

omshell has been an integral part of the ISC DHCP distribution for many years, providing a powerful interface for interacting with the DHCP server's OMAPI. Its development is tied directly to the evolution of the OMAPI protocol, which was introduced to allow dynamic management of DHCP objects without requiring a server restart. It reflects ISC's commitment to providing robust and manageable network services.

dhcpd(8), dhclient(8), dhcpd.conf(5), omapi(3)