omshell(1)
NAME
omshell - OMAPI Command Shell
SYNOPSIS
omshell
DESCRIPTION
The OMAPI Command Shell, omshell, provides an interactive way to connect to, query, and possibly change, the ISC DHCP Server's state via OMAPI, the Object Management API. By using OMAPI and omshell, you do not have to stop, make changes, and then restart the DHCP server, but can make the changes while the server is running. Omshell provides a way of accessing OMAPI. OMAPI is simply a communications mechanism that allows you to manipulate objects. In order to actually use omshell, you must understand what objects are available and how to use them. Documentation for OMAPI objects can be found in the documentation for the server that provides them - for example, in the dhcpd(1) manual page and the dhclient(1) manual page.
CONTRIBUTIONS
This software is free software. At various times its development has been underwritten by various organizations, including the ISC and Vixie Enterprises. The development of 3.0 has been funded almost entirely by Nominum, Inc. At this point development is hosted by the ISC, but the future of this project depends on you. If you have features you want, please consider implementing them.
LOCAL AND REMOTE OBJECTS
Throughout this document, there are references to local and remote objects. Local objects are ones created in omshell with the new command. Remote objects are ones on the server: leases, hosts, and groups that the DHCP server knows about. Local and remote objects are associated together to enable viewing and modification of object attributes. Also, new remote objects can be created to match local objects.
OPENING A CONNECTION
omshell is started from the command line. Once omshell is started,
there are several commands that can be issued:
server address
where address is the IP address of the DHCP server to connect to.
If this is not specified, the default server is 127.0.0.1
(localhost).
port number
where number is the port that OMAPI listens on. By default, this
is 7911.
key name secret
This specifies the TSIG key to use to authenticate the OMAPI
transactions. name is the name of a key defined in dhcpd.conf
with the omapi-key statement. The secret is the secret key
generated from dnssec-keygen or another key generation program.
connect
This starts the OMAPI connection to the server as specified by the
server statement.
CREATING LOCAL OBJECTS
Any object defined in OMAPI can be created, queried, and/or modified. The object types available to OMAPI are defined in dhcpd(8) and dhclient(8). When using omshell, objects are first defined locally, manipulated as desired, and then associated with an object on the server. Only one object can be manipulated at a time. To create a local object, use new object-type object-type is one of group, host, or lease. At this point, you now have an object that you can set properties on. For example, if a new lease object was created with new lease, any of a lease's attributes can be set as follows: set attribute-name = value Attribute names are defined in dhcpd(8) and dhclient(8). Values should be quoted if they are strings. So, to set a lease's IP address, you would do the following: set ip-address = 192.168.4.50
ASSOCIATING LOCAL AND REMOTE OBJECTS
At this point, you can query the server for information about this lease, by open Now, the local lease object you created and set the IP address for is associated with the corresponding lease object on the DHCP server. All of the lease attributes from the DHCP server are now also the attributes on the local object, and will be shown in omshell.
VIEWING A REMOTE OBJECT
To query a lease of address 192.168.4.50, and find out its attributes, after connecting to the server, take the following steps: new lease This creates a new local lease object. set ip-address = 192.168.4.50 This sets the local object's IP address to be 192.168.4.50 open Now, if a lease with that IP address exists, you will see all the information the DHCP server has about that particular lease. Any data that isn't readily printable text will show up in colon-separated hexadecimal values. In this example, output back from the server for the entire transaction might look like this: > new "lease" obj: lease > set ip-address = 192.168.4.50 obj: lease ip-address = c0:a8:04:32 > open obj: lease ip-address = c0:a8:04:32 state = 00:00:00:02 dhcp-client-identifier = 01:00:10:a4:b2:36:2c client-hostname = "wendelina" subnet = 00:00:00:06 pool = 00:00:00:07 hardware-address = 00:10:a4:b2:36:2c hardware-type = 00:00:00:01 ends = dc:d9:0d:3b starts = 5c:9f:04:3b tstp = 00:00:00:00 tsfp = 00:00:00:00 cltt = 00:00:00:00 As you can see here, the IP address is represented in hexadecimal, as are the starting and ending times of the lease.
MODIFYING A REMOTE OBJECT
Attributes of remote objects are updated by using the set command as before, and then issuing an update command. The set command sets the attributes on the current local object, and the update command pushes those changes out to the server. Continuing with the previous example, if a set client-hostname = "something-else" was issued, followed by an update command, the output would look about like this: > set client-hostname = "something-else" obj: lease ip-address = c0:a8:04:32 state = 00:00:00:02 dhcp-client-identifier = 01:00:10:a4:b2:36:2c client-hostname = "something-else" subnet = 00:00:00:06 pool = 00:00:00:07 hardware-address = 00:10:a4:b2:36:2c hardware-type = 00:00:00:01 ends = dc:d9:0d:3b starts = 5c:9f:04:3b tstp = 00:00:00:00 tsfp = 00:00:00:00 cltt = 00:00:00:00 > update obj: lease ip-address = c0:a8:04:32 state = 00:00:00:02 dhcp-client-identifier = 01:00:10:a4:b2:36:2c client-hostname = "something-else" subnet = 00:00:00:06 pool = 00:00:00:07 hardware-address = 00:10:a4:b2:36:2c hardware-type = 00:00:00:01 ends = dc:d9:0d:3b starts = 5c:9f:04:3b tstp = 00:00:00:00 tsfp = 00:00:00:00 cltt = 00:00:00:00
NEW REMOTE OBJECTS
New remote objects are created much in the same way that existing
server objects are modified. Create a local object using new, set the
attributes as you'd wish them to be, and then create the remote object
with the same properties by using
create
Now a new object exists on the DHCP server which matches the properties
that you gave your local object. Objects created via OMAPI are saved
into the dhcpd.leases file.
For example, if a new host with the IP address of 192.168.4.40 needs to
be created it would be done as follows:
> new host
obj: host
> set name = "some-host"
obj: host
name = "some-host"
> set hardware-address = 00:80:c7:84:b1:94
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
> set hardware-type = 1
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 1
> set ip-address = 192.168.4.40
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 1
ip-address = c0:a8:04:28
> create
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 00:00:00:01
ip-address = c0:a8:04:28
>
Your dhcpd.leases file would then have an entry like this in it:
host some-host {
dynamic;
hardware ethernet 00:80:c7:84:b1:94;
fixed-address 192.168.4.40;
}
The dynamic; line is to denote that this host entry did not come from
dhcpd.conf, but was created dynamically via OMAPI.
RESETTING ATTRIBUTES
If you want to remove an attribute from an object, you can do this with the unset command. Once you have unset an attribute, you must use the update command to update the remote object. So, if the host "some- host" from the previous example will not have a static IP address anymore, the commands in omshell would look like this: obj: host name = "some-host" hardware-address = 00:80:c7:84:b1:94 hardware-type = 00:00:00:01 ip-address = c0:a8:04:28 > unset ip-address obj: host name = "some-host" hardware-address = 00:80:c7:84:b1:94 hardware-type = 00:00:00:01 ip-address = <null> >
REFRESHING OBJECTS
A local object may be refreshed with the current remote object properties using the refresh command. This is useful for object that change periodically, like leases, to see if they have been updated. This isn't particularly useful for hosts.
DELETING OBJECTS
Any remote object that can be created can also be destroyed. This is done by creating a new local object, setting attributes, associating the local and remote object using open, and then using the remove command. If the host "some-host" from before was created in error, this could be corrected as follows: obj: host name = "some-host" hardware-address = 00:80:c7:84:b1:94 hardware-type = 00:00:00:01 ip-address = c0:a8:04:28 > remove obj: <null> >
HELP
The help command will print out all of the commands available in omshell, with some syntax pointers.
SEE ALSO
dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
AUTHOR
omshell is maintained by ISC. To learn more about Internet Systems
Consortium, see https://www.isc.org
omshell(1)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
