Container Record Formats

The Solaris DHCP service uses two types of DHCP containers: the dhcptab container and the DHCP network container.

The dhcptab container holds DHCP configuration data, described in the dhcptab man page. Only one instance of a dhcptab container is maintained in the DHCP service.

dhcptab records are passed between the Framework Configuration Layer and the Service Provider Layer by way of an internal structure, dt_rec_t. The include file /usr/include/dhcp_svc_public.h shows the structure.

Your public module must ensure that there are no duplicate dhcptab records. No two records can have identical key field values.

DHCP network containers contain IP address records, described in the dhcp_network man page. These containers are named to indicate the data store and the dotted IP address of the network to which the IP addresses belong, such as 10.0.0.0. Any number of DHCP network containers may exist, one for each network supported by the DHCP service.

DHCP network records are passed between the Framework Configuration Layer and the Service Provider Layer by way of an internal structure, dn_rec_t. The include file /usr/include/dhcp_svc_public.h shows the structure.

Your public module must ensure that there are no duplicate network container records. No two records can have identical key field values.

Passing Data Store Configuration Data

The Solaris DHCP data access architecture provides an optional feature for passing data-store-specific configuration data to the public module (and thus the data store). This feature is implemented as an ASCII string which is passed through the DHCP service management interface (dhcpconfig or dhcpmgr) and stored by the Framework Configuration Layer on the DHCP server machine. See the dhcpsvc.conf(4) man page for more information. You determine what kind of information is passed in the string, and the DHCP administrator provides the value of the string through the administration tool. The string might, for example, contain a user name and password needed to log in to a database.

To obtain the information from the DHCP administrator, you must write a JavaBeans™ component to present an appropriate dialog. The information is then passed to the management interface as a single ASCII string. You should document the format of the ASCII string token to facilitate debugging. To support this feature, the public module must implement and export the configure() function, described in Chapter 3, Service Provider Layer API.

Note - The architecture does not encrypt the ASCII string. It is saved in clear text in the /etc/inet/dhcpsvc.conf file. If you require encrypted information, the bean must encrypt the information before passing it to the Framework Configuration Layer.

Upgrading Container Versions

You do not need to be concerned with container version upgrades, because the architecture facilitates the coexistence of different container versions when you follow the naming guidelines described in "Naming the Public Module and Data Store Containers". The administrative tools use this feature of the architecture to enable DHCP administrators to automatically upgrade from one container version to another.

The container format version is set in the Framework Configuration Layer configuration file automatically, either by the installation (when upgrading Solaris DHCP) or through the administrative interface during initial DHCP service configuration. If you install a new version of a public module that includes a new container version, the administrative interface automatically detects the new version, and asks the administrator to decide whether to upgrade the public module version. The upgrade can be deferred. The DHCP service will continue to run with the original version of the public module until the administrator upgrades the module.

Data Service Configuration and DHCP Management Tools

The dhcpmgr and dhcpconfig management tools provide DHCP service configuration capabilities to system administrators. If you want your module to be available to users of the tools so they can configure the underlying data service, you must provide a JavaBeans™ component, known as a bean, for the public module.

The bean provides the public module with the context necessary to set the PATH variable, and optionally the RESOURCE_CONFIG variable, in dhcpsvc.conf.

Public module management beans must meet the following packaging requirements.

The public module management bean must be archived as a JAR file. The name of the JAR file must consist of the name of the public module and a .jar suffix. For example, the name of the public module management bean for the ds_SUNWfiles.so public module is SUNWfiles.jar.
The JAR file must contain a manifest that identifies the bean class. For example, the manifest for the SUNWfiles.jar JAR file contains:

Name: com/sun/dhcpmgr/client/SUNWfiles/SUNWfiles.class

Java-Bean: True

The com/sun/dhcpmgr/client/SUNWfiles/SUNWfiles.class class is the Java class that implements the com/sun/dhcpmgr/client/DSModule interface.


2. Architecture Features for Module Writers Naming the Public Module and Data Store Containers Container Name


	Container Record Formats The Solaris DHCP service uses two types of DHCP containers: the `dhcptab` container and the DHCP network container. The `dhcptab` container holds DHCP configuration data, described in the `dhcptab` man page. Only one instance of a `dhcptab` container is maintained in the DHCP service. `dhcptab` records are passed between the Framework Configuration Layer and the Service Provider Layer by way of an internal structure, `dt_rec_t`. The include file `/usr/include/dhcp_svc_public.h` shows the structure. Your public module must ensure that there are no duplicate `dhcptab` records. No two records can have identical key field values. DHCP network containers contain IP address records, described in the `dhcp_network` man page. These containers are named to indicate the data store and the dotted IP address of the network to which the IP addresses belong, such as 10.0.0.0. Any number of DHCP network containers may exist, one for each network supported by the DHCP service. DHCP network records are passed between the Framework Configuration Layer and the Service Provider Layer by way of an internal structure, `dn_rec_t`. The include file `/usr/include/dhcp_svc_public.h` shows the structure. Your public module must ensure that there are no duplicate network container records. No two records can have identical key field values. Passing Data Store Configuration Data The Solaris DHCP data access architecture provides an optional feature for passing data-store-specific configuration data to the public module (and thus the data store). This feature is implemented as an ASCII string which is passed through the DHCP service management interface (`dhcpconfig` or `dhcpmgr`) and stored by the Framework Configuration Layer on the DHCP server machine. See the `dhcpsvc.conf(4)` man page for more information. You determine what kind of information is passed in the string, and the DHCP administrator provides the value of the string through the administration tool. The string might, for example, contain a user name and password needed to log in to a database. To obtain the information from the DHCP administrator, you must write a JavaBeans™ component to present an appropriate dialog. The information is then passed to the management interface as a single ASCII string. You should document the format of the ASCII string token to facilitate debugging. To support this feature, the public module must implement and export the `configure()` function, described in Chapter 3, Service Provider Layer API. Note - The architecture does not encrypt the ASCII string. It is saved in clear text in the `/etc/inet/dhcpsvc.conf` file. If you require encrypted information, the bean must encrypt the information before passing it to the Framework Configuration Layer. Upgrading Container Versions You do not need to be concerned with container version upgrades, because the architecture facilitates the coexistence of different container versions when you follow the naming guidelines described in "Naming the Public Module and Data Store Containers". The administrative tools use this feature of the architecture to enable DHCP administrators to automatically upgrade from one container version to another. The container format version is set in the Framework Configuration Layer configuration file automatically, either by the installation (when upgrading Solaris DHCP) or through the administrative interface during initial DHCP service configuration. If you install a new version of a public module that includes a new container version, the administrative interface automatically detects the new version, and asks the administrator to decide whether to upgrade the public module version. The upgrade can be deferred. The DHCP service will continue to run with the original version of the public module until the administrator upgrades the module. Data Service Configuration and DHCP Management Tools The `dhcpmgr` and `dhcpconfig` management tools provide DHCP service configuration capabilities to system administrators. If you want your module to be available to users of the tools so they can configure the underlying data service, you must provide a JavaBeans™ component, known as a bean, for the public module. The bean provides the public module with the context necessary to set the `PATH` variable, and optionally the `RESOURCE_CONFIG` variable, in `dhcpsvc.conf`. Public Module Management Bean API Functions The `dhcpmgr` tool provides an interface, `com/sun/dhcpmgr/client/DSModule`, which defines the API functions that the public module management bean must implement. The `DSModule` interface is contained in the `dhcpmgr.jar` file. In order to compile the bean against this interface, you must add `/usr/sadm/admin/dhcpmgr/dhcpmgr.jar` to the `javac` class path. For example, for your bean named `myModule.java`, type `javac -classpath /usr/sadm/admin/dhcpmgr/dhcpmgr.jar myModule.java` `getComponent()` Synopsis `abstract java.awt.Component getComponent()` Description Returns a component that is displayed as one of the wizard steps for the DHCP Configuration Wizard. The returned component should be a panel containing GUI components to be used to obtain data-store-specific data from the user during configuration. The configuration data itself will be returned to the wizard as a result of calls to the `getPath()` and `getAdditional()` methods. See "`getPath()`" and "`getAdditional()`" for more information. `getDescription()` Synopsis `abstract java.lang.String getDescription()` Description Returns a description that is used by the DHCP Configuration Wizard when it adds the data store to the list of data store selections. For example, the management bean for the `ds_SUNWfiles.so` public module returns "Text files" as the description. `getPath()` Synopsis `abstract java.lang.String getPath()` Description Returns the path/location that is used by the data store (the `PATH` value in the Framework Configuration Layer configuration file `/etc/inet/dhcpsvc.conf`), or null if not set. The path/location value should be supplied by the user by interaction with the management bean's component. See "Passing Data Store Configuration Data". `getAdditional()` Synopsis `abstract java.lang.String getAdditional()` Description Returns additional data-store-specific information, such as the `RESOURCE_CONFIG` value in the Framework Configuration Layer configuration file `/etc/inet/dhcpsvc.conf`. The value returned by this method is most likely supplied by the user by interaction with the management bean's component. See "Passing Data Store Configuration Data". Public Module Management Bean Packaging Requirements Public module management beans must meet the following packaging requirements. The public module management bean must be archived as a JAR file. The name of the JAR file must consist of the name of the public module and a .`jar` suffix. For example, the name of the public module management bean for the `ds_SUNWfiles.so` public module is `SUNWfiles.jar`. The JAR file must contain a manifest that identifies the bean class. For example, the manifest for the `SUNWfiles.jar` JAR file contains: `Name: com/sun/dhcpmgr/client/SUNWfiles/SUNWfiles.class` `Java-Bean: True` The `com/sun/dhcpmgr/client/SUNWfiles/SUNWfiles.class` class is the Java class that implements the `com/sun/dhcpmgr/client/DSModule` interface.