806-6829 - Solaris DHCP Service Developer's Guide

8/3/2019 806-6829 - Solaris DHCP Service Developer's Guide

1/52

Solaris DHCP Service Developer's Guide

Part No:806682911September2002


2/52

Copyright 2002 Sun Microsystems 4150NetworkCircle,SantaClara,CA 95054 U.S.A.

This product or document is protectedby copyrightand distributed under licenses restricting itsuse, copying, distribution, anddecompilation.No part o thisproduct or document maybe reproduced in anyorm by anymeanswithout priorwritten authorization o Sunand itslicensors, i any. Third-party sotware,including ont technology,is copyrighted and licensed rom Sun suppliers.

Partso theproduct maybe derived rom Berkeley BSDsystems, licensed rom theUniversity o Caliornia. UNIX is a registered trademarkin theU.S. andothercountries,exclusively licensed through X/Open Company, Ltd.

Sun, Sun Microsystems, the Sun logo,docs.sun.com, AnswerBook, AnswerBook2, JavaBeans and Solaris are trademarks,registered trademarks,or service marksoSunMicrosystems,Inc. in theU.S. andothercountries. AllSPARC trademarks areused under license andare trademarks or registered trademarks o SPARCInternational,Inc. in the U.S. and othercountries. Products bearing SPARC trademarksare basedupon an architecture developed by Sun Microsystems, Inc.

TheOPENLOOK andSun GraphicalUser Interacewas developedby SunMicrosystems, Inc. orits users andlicensees. Sunacknowledges thepioneering efortsoXerox in researching anddeveloping theconcept o visualor graphicaluser interaces orthe computer industry.Sun holds a non-exclusive license rom Xerox to theXerox GraphicalUser Interace, which license also coversSun'slicensees whoimplement OPEN LOOK GUIs andotherwise complywith Sun's written licenseagreements.

Federal Acquisitions: CommercialSotwareGovernmentUsers Subject to Standard License Termsand Conditions.

DOCUMENTATIONIS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANYIMPLIED WARRANTY OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPTTO

THEEXTENT THAT SUCH DISCLAIMERS AREHELD TO BE LEGALLY INVALID.

Copyright 2002 Sun Microsystems 4150NetworkCircle,SantaClara,CA 95054 U.S.A.

Ce produit ou document estprotg parun copyrightet distribuavec deslicencesqui en restreignentl'utilisation,la copie,la distribution, et la dcompilation.Aucune partiede ce produit ou document ne peut tre reproduite sous aucuneorme, parquelquemoyenque ce soit, sans l'autorisation pralableet critede Sunetde sesbailleurs de licence, s'il y en a. Le logiciel dtenupar destiers, et quicomprendla technologie relative auxpolices de caractres, estprotg parun copyrightetlicenci pardes ournisseurs de Sun.

Desparties de ce produit pourront tre drives du systme Berkeley BSDlicencis parl'Universit de Caliornie. UNIX estune marquedpose auxEtats-Unisetdans d'autres pays et licencie exclusivement par X/Open Company, Ltd.

Sun, SunMicrosystems, le logo Sun, docs.sun.com,AnswerBook, AnswerBook2, JavaBeans et Solaris sont desmarques de abrique ou desmarques dposes,oumarques de service, de SunMicrosystems, Inc. auxEtats-Uniset dans d'autres pays. Toutesles marques SPARCsont utilisessous licence et sont desmarques deabrique ou desmarques dposes de SPARCInternational,Inc. auxEtats-Uniset dans d'autres pays. Lesproduitsportant lesmarques SPARCsont bass surunearchitecture dveloppepar Sun Microsystems, Inc.

L'interace d'utilisation graphiqueOPENLOOK et Suna tdveloppe parSun Microsystems, Inc. pour ses utilisateurset licencis. Sunreconnat leseforts depionniersde Xeroxpour la recherche et le dveloppement du concept des interacesd'utilisation visuelle ou graphique pour l'industrie de l'inormatique.Sun dtientunelicence nonexclusive de Xerox surl'interaced'utilisation graphiqueXerox, cette licence couvrant galementles licencisde Sunqui mettent en place l'interaced'utilisation graphiqueOPENLOOK et quien outre se conorment auxlicencescrites de Sun.

CETTEPUBLICATIONEST FOURNIE EN L'ETAT ET AUCUNE GARANTIE, EXPRESSE OU IMPLICITE, N'EST ACCORDEE, Y COMPRIS DESGARANTIES CONCERNANT LA VALEURMARCHANDE, L'APTITUDEDE LA PUBLICATIONA REPONDRE A UNE UTILISATIONPARTICULIERE, OULE FAITQU'ELLE NE SOIT PAS CONTREFAISANTE DE PRODUIT DE TIERS.CE DENI DE GARANTIE NE S'APPLIQUERAITPAS, DANS LA MESUREOUILSERAITTENU JURIDIQUEMENT NULET NON AVENU.

110417@25097


3/52

Contents

Preace .....................................................................................................................................................9

1 Overview o Solaris DHCP Data Access Architecture ..................................................................... 13

Modular Framework ........................................................................................................................... 13

DHCP Server Multithreading ............................................................................................................ 14

Data Access Layers .............................................................................................................................. 14

The Framework Conguration Layer ............................................................................................... 15

The Service Provider Layer API ......................................................................................................... 16

Data Store Containers ......................................................................................................................... 17

2 ArchitectureFeaturesor ModuleWriters ....................................................................................... 19

Function Categories ............................................................................................................................ 19

Considerations or Multithreading ................................................................................................... 20

Synchronizing Access to File-System-Based Containers ............................................................... 20

Avoiding Update Collisions ............................................................................................................... 21

Naming the Public Module and Data Store Containers ................................................................. 22

Public Module Name ................................................................................................................... 22

Container Name ........................................................................................................................... 23

Container Record Formats ................................................................................................................. 23

Passing Data Store Conguration Data ............................................................................................ 24Upgrading Container Versions ......................................................................................................... 24

Data Service Conguration and DHCP Management Tools ......................................................... 25

Public Module Management Bean API Functions ................................................................... 25

Public Module Management Bean Packaging Requirements ................................................. 26

3 Service Provider Layer API .................................................................................................................29General Data Store Functions ............................................................................................................ 29

3


4/52

configure() ................................................................................................................................. 29

mklocation() ............................................................................................................................... 30

status() ....................................................................................................................................... 31version() ..................................................................................................................................... 31

dhcptab Functions .............................................................................................................................. 32

list_dt() ..................................................................................................................................... 32

open_dt() ..................................................................................................................................... 32

lookup_dt() ................................................................................................................................. 33

add_dt() ....................................................................................................................................... 34

modify_dt() ................................................................................................................................. 35

delete_dt() ................................................................................................................................. 35

close_dt() ................................................................................................................................... 36

remove_dt() ................................................................................................................................. 36

DHCP Network Container Functions .............................................................................................. 37

list_dn() ..................................................................................................................................... 37

open_dn() ..................................................................................................................................... 37

lookup_dn() ................................................................................................................................. 38

add_dn() ....................................................................................................................................... 39

modify_dn() ................................................................................................................................. 39

delete_dn() ................................................................................................................................. 40

close_dn() ................................................................................................................................... 40

remove_dn() ................................................................................................................................. 41Generic Error Codes ........................................................................................................................... 41

4 Code Samples and Testing .................................................................................................................43

Code Templates ................................................................................................................................... 43

General API Functions ................................................................................................................ 43

dhcptab API Functions ............................................................................................................... 44DHCP Network Container API Functions ............................................................................... 47

Testing the Public Module .................................................................................................................. 49

Index ......................................................................................................................................................51

Contents

Solaris DHCP Service Developer's Guide September 20024


5/52

Tables

TABLE 11 Service Provider Layer API Functions .................................................................... 16

5


6/52

6


7/52

Figures

FIGURE 11 Architecture o Data Store Access in DHCP Service ............................................. 15

7


8/52

8


9/52

Preace

This Solaris DHCPService Developer's Guide provides inormation or developers who want to

use a data storage acility not currently supported by the SolarisTM

DHCP service. The manualgives an overview o the data access ramework used by Solaris DHCP, general guidelines ordevelopers, and a listing o the API unctions you use to write a module to support the new datastore.

Who Should UseThis Book

This book is intended or Solaris programmers interested in extending the data storage choicesavailable to the Solaris DHCP service.

How This Book Is OrganizedThis book consists o the ollowing chapters:

Chapter 1, Overview o Solaris DHCP Data Access Architecture, provides an overview o thearchitecture used or data access in the DHCP service.

Chapter 2, Architecture Features or Module Writers, discusses what the architecture requireso you.

Chapter 3, Service Provider Layer API, describes the API unctions you will export.

Chapter 4, Code Samples and Testing, provides sample code templates and pointers tolocations on Sun's web site where you can nd additional aids or writing and debugging codeor the public module.

9


10/52

Accessing Sun Documentation OnlineThe docs.sun.com Web site enables you to access Sun technical documentation online. You canbrowse the docs.sun.com archive or search or a specic book title or subject. The URL ishttp://docs.sun.com.

Typographic ConventionsThe ollowing table describes the typographic changes used in this book.

TABLEP1 Typographic Conventions

Typeface or Symbol Meaning Example

AaBbCc123 The names o commands, les, and directories;on-screen computer output

Edit your .login le.

Use ls -a to list all les.

machine_name% you have mail.

AaBbCc123 What you type, contrasted with on-screencomputer output

machine_name% su

Password:

AaBbCc123 Command-line placeholder: replace with a realname or value

To delete a le, typermflename.

AaBbCc123 Book titles, new words, or terms, or words to beemphasized.

Read Chapter 6 inUser'sGuide.

These are called class options.

You must be rootto do this.

Shell Prompts in Command ExamplesThe ollowing table shows the deault system prompt and superuser prompt or the C shell,Bourne shell, and Korn shell.

TABLEP2 ShellPrompts

Shell Prompt

C shell prompt machine_name%

C shell superuser prompt machine_name#

Bourne shell and Korn shell prompt $

Bourne shell and Korn shell superuser prompt #

Preace

http://docs.sun.com/http://docs.sun.com/


11/52

Preace

11


12/52

12


13/52

Overview o Solaris DHCP Data AccessArchitecture

This chapter presents an overview o the architecture o the Solaris Dynamic HostConguration Protocol (DHCP) service introduced in the Solaris 8 7/01 operatingenvironment. This overview can help you see where your work will t into the architecture.

For general inormation about the Solaris DHCP service, seeChapter 7, About Solaris DHCP

(Overview), in SystemAdministrationGuide: IP Services.

The ollowing topics are included:

Modular Framework on page 13 DHCP Server Multithreading on page 14 Data Access Layers on page 14 The Framework Conguration Layer on page 15

The Service Provider Layer API on page 16 Data Store Containers on page 17

Modular Framework

The Solaris DHCP service includes the DHCP daemon, administrative tools, and separate data

access modules (calledpublic modules) or diferent data storage acilities. Solaris DHCPprovides an API that enables you to write your own public modules, implemented as sharedobjects, to support any data storage acility you want. When you integrate your public moduleinto the Solaris DHCP ramework, the DHCP service stores its data in your database using yourpublic module. Public modules can be delivered independently o the Solaris DHCP service,enabling anyone to develop and deliver modules to support any data storage acility.

The rst release o Solaris DHCP using this architecture provides public modules or ASCII

les, NIS+, and le-system-based binary data stores. This manual provides inormation thatenables developers to create their own public modules or any database.

1C H A P T E R 1

13
http://www.oracle.com/pls/topic/lookup?ctx=806-4075&id=dhcp-overview-1http://www.oracle.com/pls/topic/lookup?ctx=806-4075&id=dhcp-overview-1http://www.oracle.com/pls/topic/lookup?ctx=806-4075&id=dhcp-overview-1http://www.oracle.com/pls/topic/lookup?ctx=806-4075&id=dhcp-overview-1http://www.oracle.com/pls/topic/lookup?ctx=806-4075&id=dhcp-overview-1


14/52

DHCP Server Multithreading

The DHCP server implements multithreading, enabling it to service many clientssimultaneously. Public modules are required to be MT-SAFE to support multithreading by theDHCP server, and this in itsel allows the DHCP service to handle a larger number o clients.However, the capacity o the DHCP server is largely dependent on the capabilities o the datastorage acility and the eciency o the public module used to access the data. You canpotentially increase the perormance and capacity o your Solaris DHCP service by creating apublic module or using a ast, high-capacity data storage acility.

Data Access Layers

The Solaris DHCP modular ramework implementation employs the ollowing data accesslayers:

Application/Service Layer, consisting o all consumers o DHCP service data such as theDHCP daemon (in.dhcpd), command line management utilities (pntadm, dhtadm,dhcpconfig), dhcpmgr, and report generators. These data consumers interace with theDHCP service using calls to API unctions implemented by the Framework CongurationLayer o the architecture.

Framework Conguration Layer, consisting o the shared librarylibdhcpsvc.so and the/etc/inet/dhcpsvc.conf conguration le. The Framework Conguration Layerconnects the Application/Service Layer and the Service Provider Layer. See TheFramework Conguration Layer on page 15 or more inormation about the Framework

Conguration Layer. Service Provider Layer, consisting o public modules that implement the Service Provider

API unctions, which are used by the Application/Service Layer through the FrameworkConguration Layer to manipulate the data store containers and the records within them.The data store containers are the dhcptab and DHCP network tables.

The ollowing gure shows the interaction o the architecture layers.

DHCPServer Multithreading



15/52

The Framework Confguration Layer

Functions implemented in libdhcpsvc.so are used by the Application/Service Layer to:

locate, load, and unload public modules manage data container version changes access the data store containers manipulate data store records in the containers

The /etc/inet/dhcpsvc.conf contains a number o conguration parameters or the DHCPservice, including the ollowing keywords relevant to the public module developer:

RESOURCE Public module to load. The value oRESOURCE matches the public

module name. For example, the RESOURCE=SUNWfiles reers to publicmodule ds_SUNWfiles.so. Naming the Public Module and Data StoreContainers on page 22 explains the rules or naming public modules.

PATH Location o DHCP containers within the data service that the publicmodule exports. The value oPATH is specic to the data service. Forexample, a UNIXTM path name would be assigned to PATH or theSUNWfiles resource.

FIGURE 11 Architecture o DataStore Access in DHCP Service

The Framework Confguration Layer

Chapter 1 Overview o Solaris DHCP Data Access Architecture 15


16/52

RESOURCE_CONFIG Conguration inormation specic to the public module. This is anoptional keyword that you can use i the data service requiresconguration inormation, such as authentication rom the user. I you

use this keyword, you must provide a public module management beanto prompt the user or inormation to set the keyword value. SeegetComponent()onpage25. The module must also export theconfigure() unction to receive the value o this keyword duringmodule load time. Seeconfigure()onpage29 or more inormation.

The Framework Conguration Layer also provides to the Service Provider Layer an optionalAPI synchronization service, described in Synchronizing Access to File-System-Based

Containers on page 20.

The Service Provider Layer APIThe Service Provider Layer API consists o unctions, data structures, and maniest constantscontained in the /usr/include/dhcp_svc_public.h le.

The unctions are summarized in the ollowing table, with links to sections with more detailabout each unction.

TABLE 11 Service Provider Layer API Functions

API Function Use

General unctions or all data store containers

configure()onpage29 Pass a conguration string to the data store. Optional unction.

mklocation()onpage30 Create the location in which the data store will reside.

status()onpage31 Return general status inormation or the data store.

version()onpage31 Return the version o the Service Provider Layer API implementedby the data store container.

Functions or dhcptab containers

list_dt()onpage32 Return the dhcptab container name.

open_dt()onpage32 Open or create the dhcptab container.

lookup_dt()onpage33 Perorm a query or records in the dhcptab container.

add_dt()onpage34 Add a record to the dhcptab container.

modify_dt()onpage35 Modiy an existing record in the dhcptab container.

delete_dt()

onpage35 Delete a recordrom thedhcptab

container.

TheService Provider Layer API



17/52

TABLE 11 Service Provider Layer API Functions (Continued)API Function Use

close_dt()onpage36 Close the dhcptab container.

remove_dt()onpage36 Remove the dhcptab container rom the data store.

Functions or DHCP network containers

list_dn()onpage37 Return a list o DHCP network container names.

open_dn()onpage37 Openor create a DHCP network container.

lookup_dn()onpage38 Perorm a query or records in a DHCP network container.

add_dn()onpage39 Add a record to a DHCP network container.

modify_dn()onpage39 Modiy an existing record in a DHCP network container.

delete_dn()onpage40 Delete a recordrom a DHCP network container.

close_dn()onpage40 Close a DHCP network container.

remove_dn()onpage41 Remove a DHCP network container rom the data store.

Data Store ContainersThe dhcptab and DHCP network tables are reerred to generically as data store containers. Bydeault, Solaris DHCP provides support or the container ormats shown in the ollowing table.

Data Service Supported Public Module

File-system-based, ASCII ormat ds_SUNWfiles.so

NIS+ service ds_SUNWnisplus.so

File-system-based, binary ormat ds_SUNWbinfiles.so

DataStore Containers

Chapter 1 Overview o Solaris DHCP Data Access Architecture 17


18/52

18


19/52

Architecture Features or ModuleWriters

This chapter discusses architectural details you should keep in mind when creating a publicmodule or a data service.


Function Categories on page 19 Considerations or Multithreading on page 20 Synchronizing Access to File-System-Based Containers on page 20 Avoiding Update Collisions on page 21 Naming the Public Module and Data Store Containers on page 22 Container Record Formats on page 23 Passing Data Store Conguration Data on page 24 Upgrading Container Versions on page 24 Data Service Conguration and DHCP Management Tools on page 25

Function Categories

The Service Provider Layer API unctions can be divided into three categories:

Data store unctions, which acilitate activities related to the public module and underlyingdata service themselves. These unctions include configure(), mklocation(), status(),and version().

dhcptab container unctions, which acilitate the creation o the dhcptab container, thewriting o records to the dhcptab container, and the query o records in the dhcptab

container. The open_dt() unction creates a handle or the container, and the otherunctions take a pointer to that handle. The close_dt() unction destroys the handle whenit closes the container.

2C H A P T E R 2

19


20/52

Network container unctions, which acilitate the creation o DHCP network containers, thewriting o records to the network containers, and the query o records in the networkcontainers. The open_dn() unction creates a handle or the container, and the other

unctions take a pointer to that handle. The close_dn() unction destroys the handle whenit closes the container.

The unctions are described in more detail in Chapter 3, Service Provider Layer API.

Considerations or Multithreading

The DHCP server implements multithreading, which enables it to service many clientssimultaneously. Public modules are required to be MT-SAFE to support multithreading by theDHCP server.

To make your module MT-SAFE, you must synchronize calls to add_d?(), delete_d?(),andmodify_d?() so that they are called serially. For example, i one thread is inside add_dn() oragiven DHCP network container, no other thread may be inside add_dn(), delete_dn(),modify_dn(), or lookup_dn() or that same container. I your public module supports a local

le-system-based data service, you can use the synchronization service to take care o this oryou. See Synchronizing Access to File-System-Based Containers on page 20 or moreinormation.

Synchronizing Access to File-System-Based ContainersWhen you write a public module that provides access to containers in a local le-system-based

data service (the data service runs on the same machine as the DHCP server), it can be dicultto synchronize access to the underlying data service between multiple processes and threads.

The Solaris DHCP synchronization service simplies the design o public modules using localle-system-based data services by pushing synchronization up into the FrameworkConguration Layer. When you design your module to use this ramework, your code becomessimpler and your design cleaner.

The synchronization service provides public modules with per-container exclusivesynchronization o all callers o the add_d?(), delete_d?(),and modify_d?() Service ProviderLayer API calls. This means that i one thread is inside add_dn() or a given DHCP networkcontainer, no other thread may be inside add_dn(), delete_dn(), modify_dn() orlookup_dn() or that same container. However, other threads may be within routines thatprovide no synchronization guarantees, such as close_dn().

Per-container shared synchronization o all callers olookup_d?() is also provided. Thus, theremay be many threads perorming a lookup on the same container, but only one thread mayperorm an add, delete, or modiy operation.

Considerations or Multithreading


A idi U d t C lli i


21/52

The synchronization service is implemented as a daemon (/usr/lib/inet/dsvclockd). Lockmanager requests are made on the public module's behal through Framework CongurationLayer API calls. The interace between the Framework Conguration layer and the lock

manager daemon uses the Solaris doors interprocess communication mechanism. See, orexample, door_create(3DOOR) and door_call(3DOOR).

The Framework Conguration layer starts the dsvclockd daemon i a public module requestssynchronization and the daemon is not already running. The daemon automatically exits i itmanages no locks or 15 minutes. To change this interval, you can create a/etc/default/dsvclockd le and set the IDLE deault to the number o idle minutes beore thedaemon terminates.

A public module noties the Framework Conguration Layer that it requires synchronizationservices by providing the ollowing global variable in one o the module's source les:

dsvc_synchtype_t dsvc_synchtype = DSVC_SYNCH_DSVCD;

A public module noties the Framework Conguration Layer that it doesnotrequiresynchronization services by including the ollowing global variable in one o the module'ssource les:

dsvc_synchtype_t dsvc_synchtype = DSVC_SYNCH_NONE;

DSVC_SYNCH_DSVCD and DSVC_SYNCH_NONE are the only two synchronization types that existcurrently.

Avoiding Update Collisions

The architecture provides a acility that helps a les-based module avoid record updatecollisions. The Service Provider API acilitates the maintenance o data consistency through theuse o a per-record update signature, an unsigned 64bit integer. The update signature is thed?_sig element o the d?_rec_t container record data structure, dened in/usr/include/dhcp_svc_public.h. All layers o the architecture use d?_rec_t records, romthe Application/Service Layer through the Framework Conguration Layer API and onthrough to the Service Provider Layer API. Above the Service Provider Layer, the updatesignature is an opaque object which is not manipulated by users o the Framework

Conguration Layer API.When a module receives a d?_rec_t record through a Service Provider Layer API unction call,it should perorm a lookup in the data service to nd a record that matches the key elds o thed?_rec_t, and compare the signature o the internal record against the d?_rec_t passed by thecall. I the signature o the internal record does not match that o the passed record, then therecord has been changed since the consumer acquired it rom the public module. In this case,the module should return DSVC_COLLISION, which inorms the caller that the record has beenchanged since it was acquired. I the signatures match, the module should increment the updatesignature o the argument record beore it stores the record.

Avoiding UpdateCollisions

Chapter 2 Architecture Features or Module Writers 21

Naming the Public Module and DataStore Containers
http://www.oracle.com/pls/topic/lookup?ctx=817-0715&id=door-create-3doorhttp://www.oracle.com/pls/topic/lookup?ctx=817-0715&id=door-create-3doorhttp://www.oracle.com/pls/topic/lookup?ctx=817-0715&id=door-call-3doorhttp://www.oracle.com/pls/topic/lookup?ctx=817-0715&id=door-call-3doorhttp://www.oracle.com/pls/topic/lookup?ctx=817-0715&id=door-call-3doorhttp://www.oracle.com/pls/topic/lookup?ctx=817-0715&id=door-create-3door


22/52

When a module receives a new d?_rec_t record through the Service Provider Layer API, themodule must assign a value to the update signature beore it adds the record to the container.The simplest way is to set the value to 1.

However, in certain rare situations a collision might not be detected i the signature always hasthe same initial value. Consider the ollowing scenario. Thread A adds a record with a signatureo 1, and Thread B looks up that record. Thread A deletes the record and creates a new recordwith the same key elds and a signature o 1 since it has just been created. Thread B thenmodies the record it looked up, but that has already been deleted. The module compares thekey elds and signatures o the record looked up by Thread B and the record in the data store,nds them to be the same, and makes the modication. Such a modication attempt should

have been a collision because the records are, in act, not the same.

The ds_SUNWfiles.so and ds_SUNWbinfiles.so modules provided with Solaris DHCPaddress such a possibility. They divide the update signature into two elds to ensure theuniqueness o each record's signature. The rst 16 bit eld o the update signature is set to arandomly generated number. This eld never changes in the record ater it is set. The lower 48bit eld o the signature is set to 1 and then incremented each time the record is updated.

Note The modules provided with Solaris DHCP illustrate one approach you can use to avoidrecord update collisions. You can devise your own method or use a similar one.

Naming the Public Module and Data Store ContainersThe public module and containers must both contain version numbers to enable the

architecture's upgrading mechanism to work.

Public Module Name

You must use the ollowing name ormat or your public module:

ds_name.so.ver

where name is the name o the module and veris the container ormat version number. Thename must use a prex that is an internationally known identier associated with yourorganization. For example, the public modules that Sun Microsystems provides have namesprexed with SUNW, the stock ticker symbol or Sun. For example, the NIS+ public module isnamed ds_SUNWnisplus.so.1. By including such an identier in the module name, you avoidpublic module name collisions in the /usr/lib/inet/dhcp/svc public module directory.

I your company name is Inet DataBase, or example, you might call your moduleds_IDBtrees.so.1

Naming the Public Module and DataStore Containers


Container Record Formats


23/52

Container NameThe container names presented to the administrator through the administrative interace must

always be dhcptab and the dotted IP network address or the DHCP network tables, such as10.0.0.0.

Internally, the data store container names must contain the version number to enable you toproduce revisions o your container ormats whenever necessary. This naming scheme allowsthe coexistence o multiple versions o a container, which is a requirement or the architecture'scontainer version upgrade mechanism to work.

The names used or the containers should include a globally recognizable token to ensure that

the names are unique.

For example, the NIS+ public module provided with Solaris DHCP would create the dhcptabcontainer internally as SUNWnisplus1_dhcptab. The container or the 172.21.174.0 networktable would be SUNWnisplus1_172.21.174.0.

I your company name is Inet DataBase, and your public module is ds_IDBtrees.so.1,youwould name your containers IDBtrees1_dhcptab and IDBtrees1_172.21.174.0.

Container Record FormatsThe Solaris DHCP service uses two types o DHCP containers: the dhcptab container and theDHCP network container.

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

dhcptab records are passed between the Framework Conguration Layer and the ServiceProvider Layer by way o an internal structure, dt_rec_t. The include le/usr/include/dhcp_svc_public.h shows the structure.

Your public module must ensure that there are no duplicate dhcptab records. No two recordscan have identical key eld 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 o thenetwork to which the IP addresses belong, such as 10.0.0.0. Any number o DHCP networkcontainers may exist, one or each network supported by the DHCP service.

DHCP network records are passed between the Framework Conguration Layer and theService Provider Layer by way o an internal structure, dn_rec_t. The include le/usr/include/dhcp_svc_public.h shows the structure.

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

Container Record Formats


PassingData Store Confguration Data


24/52

Passing Data Store Confguration DataThe Solaris DHCP data access architecture provides an optional eature or passing

data-store-specic conguration data to the public module (and thus the data store). Thiseature is implemented as an ASCII string which is passed through the DHCP servicemanagement interace (dhcpconfig or dhcpmgr) and stored by the Framework CongurationLayer on the DHCP server machine. See the dhcpsvc.conf(4) man page or more inormation.You determine what kind o inormation is passed in the string, and the DHCP administratorprovides the value o the string through the administration tool. The string might, or example,contain a user name and password needed to log in to a database.

To obtain the inormation rom the DHCP administrator, you must write a JavaBeansTM

component to present an appropriate dialog. The inormation is then passed to themanagement interace as a single ASCII string. You should document the ormat o the ASCIIstring token to acilitate debugging. To support this eature, the public module must implementand export the configure() unction, 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 le. I you require encrypted inormation, the bean must encrypt theinormation beore passing it to the Framework Conguration Layer.

Upgrading Container VersionsYou do not need to be concerned with container version upgrades, because the architectureacilitates the coexistence o diferent container versions when you ollow the naming

guidelines described in Naming the Public Module and Data Store Containers on page 22.The administrative tools use this eature o the architecture to enable DHCP administrators toautomatically upgrade rom one container version to another.

The container ormat version is set in the Framework Conguration Layer conguration leautomatically, either by the installation (when upgrading Solaris DHCP) or through theadministrative interace during initial DHCP service conguration. I you install a new versiono a public module that includes a new container version, the administrative interace

automatically detects the new version, and asks the administrator to decide whether to upgradethe public module version. The upgrade can be deerred. The DHCP service will continue torun with the original version o the public module until the administrator upgrades the module.

g g


DataService Confguration and DHCP Management Tools


25/52

Data Service Confguration and DHCP Management ToolsThe dhcpmgr and dhcpconfig management tools provide DHCP service conguration

capabilities to system administrators. I you want your module to be available to users o thetools so they can congure the underlying data service, you must provide a JavaBeansTM

component, known as a bean, or the public module.

The bean provides the public module with the context necessary to set the PATHvariable, andoptionally the RESOURCE_CONFIGvariable, in dhcpsvc.conf.

Public Module Management Bean API FunctionsThe dhcpmgr tool provides an interace,com/sun/dhcpmgr/client/DSModule, which denesthe API unctions that the public module management bean must implement.

The DSModule interace is contained in the dhcpmgr.jar le. In order to compile the beanagainst this interace, you must add /usr/sadm/admin/dhcpmgr/dhcpmgr.jar tothe javacclass path. For example, or your bean namedmyModule.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 o the wizard steps or the DHCP CongurationWizard. The returned component should be a panel containing GUI components to be used toobtain data-store-specic data rom the user during conguration. The conguration data itselwill be returned to the wizard as a result o calls to the getPath() and getAdditional()

methods. See getPath()onpage26 and getAdditional()onpage26 or moreinormation.

getDescription()

Synopsis

abstract java.lang.String getDescription()


DataService Confguration and DHCPManagement Tools


26/52

Description

Returns a description that is used by the DHCP Conguration Wizard when it adds the data

store to the list o data store selections. For example, the management bean or theds_SUNWfiles.so public module returns Text les as the description.

getPath()

Synopsis

abstract java.lang.String getPath()

Description

Returns the path/location that is used by the data store (the PATHvalue in the FrameworkConguration Layer conguration le/etc/inet/dhcpsvc.conf), or nulli not set.Thepath/location value should be supplied by the user by interaction with the management bean'scomponent. See Passing Data Store Conguration Data on page 24.

getAdditional()

Synopsis

abstract java.lang.String getAdditional()

Description

Returns additional data-store-specic inormation, such as theRESOURCE_CONFIGvalue in theFramework Conguration Layer conguration le/etc/inet/dhcpsvc.conf. The valuereturned by this method is most likely supplied by the user by interaction with the managementbean's component. See Passing Data Store Conguration Data on page 24.

Public Module Management Bean Packaging

RequirementsPublic module management beans must meet the ollowing packaging requirements.

The public module management bean must be archived as a JAR le. The name o the JARle must consist o the name o the public module and a .jar sux. For example, the nameo the public module management bean or the ds_SUNWfiles.so public module isSUNWfiles.jar.

The JAR le must contain a maniest that identies the bean class. For example, the maniest

or the SUNWfiles.jar JAR le contains:


DataService Confguration and DHCP Management Tools


27/52

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

Java-Bean: True

Thecom/sun/dhcpmgr/client/SUNWfiles/SUNWfiles.class

class is the Java class thatimplements the com/sun/dhcpmgr/client/DSModule interace.



28/52

28


29/52

Service Provider Layer API

This chapter lists and describes the API unctions exported by public modules and consumedby the Framework Conguration Layer. The unctions are grouped in sections according totheir purpose. Within each section, unctions are listed in an order in which you might usethem.

The ollowing topics are included: General Data Store Functions on page 29 dhcptab Functions on page 32 DHCP Network Container Functions on page 37 Generic Error Codes on page 41

All implementations that match a certain Service Provider Layer API version must ollow thisspecication or the API unctions they implement. Later versions o the API must be

backward-compatible with earlier versions. This means that additional API calls may be added,but existing ones cannot be changed or deleted.

See the include le /usr/include/dhcp_svc_public.h or more details about the unctions.

General Data Store FunctionsThis section lists unctions related to general data store activities.

configure()

Purpose

To pass a conguration string to the data store.

3C H A P T E R 3

29

General DataStore Functions


30/52

Synopsis

int configure(const char *configp);

Description

The configure() unction is optional. I it is provided together with the required publicmodule management bean (see getComponent()onpage25), the Framework CongurationLayer calls this unction when the public module loads, and passes in thepublic-module-specic conguration string, which is cached by the Framework CongurationLayer on the DHCP server or the data store module.

Returns

DSVC_SUCCESS, DSVC_MODULE_CFG_ERR

The configure() unction returns DSVC_SUCCESS i the module wants the FrameworkConguration Layer to continue to load the module, orDSVC_MODULE_CFG_ERR i the modulewants the Framework Conguration Layer to ail the loading o the module. An example o

such a situation is a conguration string so malormed that the required conguration o themodule cannot take place.

mklocation()

PurposeTo create the directory where the data store containers are to reside.

Synopsis

int mklocation(const char *location);

Description

Creates the directory pointed to bylocation (i the directory does not exist) or data storecontainers to reside.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_EXISTS, DSVC_BUSY, DSVC_INTERNAL,

DSVC_UNSUPPORTED.


General DataStore Functions


31/52

status()

PurposeTo obtain the general status o the data store.

Synopsis

int status(const char *location);

Description

The status() unction instructs the data store to return its general status, and ilocation isnon-NULL, urther validates the location o the data store container by determining i thecontainer does in act exist, is accessible, and is ormed correctly or the data store type. Thedata store must return the appropriate error codes i the acilities it needs are unavailable or it isotherwise not ready.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL.

version()

Purpose

To obtain the version number o the API implemented by the data store.

Synopsis

int version(int *versionp);

Description

Data stores that support the Service Provider Layer API described in this manual are version 1(one). The version is returned in the int pointed to byversionp.

Returns

DSVC_SUCCESS, DSVC_INTERNAL, DSVC_MODULE_ERR.

Chapter 3 Service Provider Layer API 31

dhcptab Functions


32/52

dhcptab FunctionsThe API unctions described in this section are used with the dhcptab container.

list_dt()

Purpose

To listthe name othe dhcptab container.

Synopsis

int list_dt(const char *location, char ***listppp, uint_t *count);

Description

Produces a dynamically allocated list odhcptab container objects (listppp) ound atlocation

and stores the number o list items incount

.Inodhcptab

container objects exist,then DSVC_SUCCESS is returned, listppp issetto NULL, and count issetto0.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NO_LOCATION.

open_dt()

Purpose

Toopena dhcptab container or create a new one.

Synopsis

int open_dt(void **handpp, const char *location, uint_t flags);

Description

Opens an existing dhcptab container or creates a new container at location and initializeshandp to point to the instance handle. Perorms any initialization needed by the data store.When creating a new dhcptab, the caller's identity is used or owner/permissions. Valid flagsinclude DSVC_CREATE, DSVC_READ, DSVC_WRITE, DSVC_NONBLOCK. Note that the creation o a

dhcptab container as read-only (DSVC_CREATE | DSVC_READ) is invalid.


dhcptab Functions


33/52

ReturnsDSVC_SUCCESS, DSVC_EXISTS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION,

DSVC_BUSY, DSVC_INTERNAL.

lookup_dt()

PurposeTo perorm a lookup query or records in the dhcptab container.

Synopsisint lookup_dt(void *handp, boolean_t partial, uint_t query, int count, const

dt_rec_t *targetp, dt_rec_list_t **resultp, uint_t *records);

Description

Searches the dhcptab container or instances that match the query described by thecombination oquery and targetp.Ithe partial argument is B_TRUE, then partial query

results are acceptable to the caller. Thus, when partial is B_TRUE, any query that returns at leastone matching record is considered successul. When partial is B_FALSE, the query returnsDSVC_SUCCESS only i it has been applied to the entire container.

The query argument consists o 2 elds, each 16 bits long. The lower 16 bits select which elds{key, type} otargetp are to be considered in the query. The upper 16 bits identiy whether aparticular eld value selected in the lower 16 bits must match (bit set) or not match (bit clear).Bits 2 through 15 in both 16-bit elds are currently unused, and must be set to 0. Useul macros

or constructing queries can be ound in Example 31.The count eld species the maximum number o matching records to return. A countvalue o-1 requests the return o all records that match, regardless o the number. A countvalue o 0causes lookup_dt to return immediately with no data.

resultp is set to point to the returned list o records. Iresultp is NULL, then the caller issimply interested in knowing how many records match the query. Note that these records aredynamically allocated, and thereore the caller is responsible or reeing them. lookup_dt()

returns the number o matching records in the records argument. A recordsvalue o 0 meansthat no records matched the query.

The ollowing example includes macros you might nd useul or constructing andmanipulating lookup queries or the DHCP network anddhcptab containers.

EXAMPLE 31 Useul Macros or Lookup Queries

/** Query macros - used for initializing query fields (lookup_d?)

*/


dhcptab Functions


34/52

EXAMPLE 31 Useul Macros or Lookup Queries (Continued)

/* dhcp network container */#define DN_QCID 0x0001#define DN_QCIP 0x0002#define DN_QSIP 0x0004#define DN_QLEASE 0x0008#define DN_QMACRO 0x0010#define DN_QFDYNAMIC 0x0020#define DN_QFAUTOMATIC 0x0040#define DN_QFMANUAL 0x0080#define DN_QFUNUSABLE 0x0100#define DN_QFBOOTP_ONLY 0x0200#define DN_QALL (DN_QCID | DN_QCIP | DN_QSIP | DN_QLEASE | \

DN_QMACRO | DN_QFDYNAMIC DN_QFAUTOMATIC |\DN_QFMANUAL | DN_QFUNUSABLE | \DN_QFBOOTP_ONLY)

/* dhcptab */#define DT_DHCPTAB "dhcptab" /* default name of container */#define DT_QKEY 0x01#define DT_QTYPE 0x02#define DT_QALL (DT_QKEY | DT_QTYPE)

/* general query macros */

#define DSVC_QINIT(q) ((q) = 0)#define DSVC_QEQ(q, v) ((q) = ((q) | (v) | ((v)


35/52

Synopsis

int add_dt(void *handp, dt_rec_t *newp);

Description

Adds the record newp to the dhcptab container reerred to byhandp. The signature associatedwith newp is updated by the underlying public module. I an update collision occurs, the datastore is not updated. The caller is responsible or reeing any dynamically allocated arguments.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL, DSVC_EXISTS.

modify_dt()

Purpose

To modiy a record in the dhcptab container.

Synopsis

int modify_dt(void *handp, const dt_rec_t *origp, dt_rec_t *newp);

Description

Atomically modies the record origp with the record newp in the dhcptab container reerred tobyhandp. The signature associated with newp is updated by the underlying public module. I anupdate collision occurs, the data store is not updated. The caller is responsible or reeing anydynamically allocated arguments.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_COLLISION, DSVC_INTERNAL, DSVC_NOENT.

delete_dt()

Purpose

To delete a record rom the dhcptab container.

Synopsis

int delete_dt(void *handp, const dt_rec_t *dtp);


dhcptab Functions


36/52

Description

Deletes the record identied by the key, type and dt_sig elds odtp rom the dhcptabcontainer reerred to by the handle handp. I an update collision occurs, the matching record is

not deleted rom the data store, and DSVC_COLLISION is returned. The caller is responsible orreeing any dynamically allocated arguments.

I the dtp signature (dt_sig) is 0, the matching record is simply deleted with no detection oupdate collisions.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_BUSY, DSVC_INTERNAL, DSVC_COLLISION.

close_dt()

Purpose

To close the dhcptab container.

Synopsis

int close_dt(void **handpp);

Description

Frees the instance handle and cleans up per-instance state.

ReturnsDSVC_SUCCESS, DSVC_ACCESS, DSVC_INTERNAL.

remove_dt()

Purpose

To delete the dhcptab container rom the data store location.

Synopsis

int remove_dt(const char *location);

Description

Removes the dhcptab container in location rom the data store.


DHCPNetwork ContainerFunctions


37/52

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY,

DSVC_INTERNAL.

DHCP Network Container FunctionsThe API unctions described in this section are used to manipulate the DHCP networkcontainers and the IP address records within them.

list_dn()

Purpose

To return a list o network containers.

Synopsisint list_dn(const char *location, char ***listppp, uint_t *count);

Description

Produces a dynamically allocated list o network container objects (listppp) ound atlocation and stores the number o list items in count. I no network container objects exist,

thenDSVC_SUCCESS

is returned,listppp

issettoNULL

, andcount

issetto0.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NO_LOCATION.

open_dn()

Purpose

To open a network container or create a new one.

Synopsis

int open_dn(void **handpp, const char *location, uint_t flags, const struct

in_addr *netp, const struct in_addr *maskp);




38/52

Description

Opens an existing DHCP network container or creates a new container specied bynetp andmaskp (both host order) in location and initializes handpp to point to the instance handle.

Perorms any initialization needed by the data store. When creating a new DHCP networkcontainer, the caller's identity is used or owner/permissions. Valid ags include DSVC_CREATE,DSVC_READ, DSVC_WRITE, DSVC_NONBLOCK. Note that the creation o a DHCP network containeras read-only (DSVC_CREATE | DSVC_READ) is invalid.

Returns

DSVC_SUCCESS, DSVC_EXISTS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION,

DSVC_BUSY, DSVC_INTERNAL, DSVC_UNSUPPORTED.

lookup_dn()

Purpose

To perorm a lookup query or records in a DHCP network container.

Synopsis

int lookup_dn(void *handp, boolean_t partial, uint_t query, int count, const

dn_rec_t *targetp, dn_rec_list_t **resultp, uint_t *records);

DescriptionSearches a DHCP network container or instances that match the query described by thecombination oquery and targetp.Ithe partial argument is B_TRUE, then partial queryresults are acceptable to the caller. Thus, when partial is B_TRUE, any query that returns at leastone matching record is considered successul. When partial is B_FALSE, the query returnsDSVC_SUCCESS only i it has been applied to the entire container.

The query argument consists o 2 elds, each 16 bits long. The lower 16 bits select which elds

{client id, ags, client IP, server IP, expiration, macro, or comment} otargetp aretobeconsidered in the query. The upper 16 bits identiy whether a particular eld value selected inthe lower 16 bits must match (bit set) or not match (bit clear). Bits 7 through 15 in both 16-bitelds are currently unused, and must be set to 0. Useul macros or constructing queries can beound in Example 31.

The count eld species the maximum number o matching records to return. A countvalue o-1 requests the return o all records that match, regardless o the number. A countvalue o 0

causes lookup_dn to return immediately with no data.


i i h d li d I i NULL h h ll i



39/52

resultp is set to point to the returned list o records. Iresultp is NULL, then the caller issimply interested in knowing how many records match the query. Note that these records aredynamically allocated, and thereore the caller is responsible or reeing them. lookup_dn()

returns the number o matching records in the records argument. A recordsvalue o 0 meansthat no records matched the query.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL.

add_dn()

Purpose

To add a record to the DHCP network container.

Synopsis

int add_dn(void *handp, dn_rec_t *newp);

Description

Adds the record newp to the DHCP network container reerred to by the handle handp.Thesignature associated with newp is updated by the underlying public module. I an updatecollision occurs, the data store is not updated.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL, DSVC_EXISTS.

modify_dn()

Purpose

To modiy a record in a DHCP network container.

Synopsis

int modify_dn(void *handp, const dn_rec_t *origp, dn_rec_t *newp);

Description

Atomically modies the record origp with the record newp in the DHCP network containerreerred to by the handle handp. The signature associated with newp is updated by the

underlying public module. I an update collision occurs, the data store is not updated.


R t



40/52

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_COLLISION, DSVC_INTERNAL, DSVC_NOENT.

delete_dn()

Purpose

To delete a record rom a DHCP network container.

Synopsisint delete_dn(void *handp, const dn_rec_t *pnp);

Description

Deletes the record identied by the dn_cip and dn_sig elements opnp rom the DHCPnetwork container reerred to by the handle handp. I an update collision occurs, the matchingrecord is not deleted rom the data store and DSVC_COLLISION is returned.

I the dn_sig signature opnp is 0, the matching record is simply deleted with no detection oupdate collisions.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_BUSY, DSVC_INTERNAL, DSVC_COLLISION.

close_dn()

Purpose

To close the network container.

Synopsis

int close_dn(void **handpp);

Description

Frees the instance handle and cleans up per-instance state.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_INTERNAL.


d ()

Generic ErrorCodes


41/52

remove_dn()

PurposeTo delete the DHCP network container rom the data store location.

Synopsis

int remove_dn(const char *location, const struct in_addr *netp);

Description

Removes DHCP network container netp (host order) in location.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY,

DSVC_INTERNAL.

Generic Error CodesThe Framework Conguration Layer and Service Provider Layer API unctions will return theollowing integer error values. Note that the le /usr/include/dhcp_svc_public.h is thedenitive source or these codes.

* Standard interface errors*/

#define DSVC_SUCCESS 0 /* success */#define DSVC_EXISTS 1 /* object already exists */#define DSVC_ACCESS 2 /* access denied */#define DSVC_NO_CRED 3 /* No underlying credential */#define DSVC_NOENT 4 /* object doesnt exist */#define DSVC_BUSY 5 /* object temporarily busy (again) */#define DSVC_INVAL 6 /* invalid argument(s) */#define DSVC_INTERNAL 7 /* internal data store error */#define DSVC_UNAVAILABLE 8 /* underlying service required by */

/* public module unavailable */

#define DSVC_COLLISION 9 /* update collision */#define DSVC_UNSUPPORTED 10 /* operation not supported */#define DSVC_NO_MEMORY 11 /* operation ran out of memory */#define DSVC_NO_RESOURCES 12 /* non-memory resources unavailable */#define DSVC_BAD_RESOURCE 13 /* malformed/missing RESOURCE setting */#define DSVC_BAD_PATH 14 /* malformed/missing PATH setting */#define DSVC_MODULE_VERSION 15 /* public module version mismatch */#define DSVC_MODULE_ERR 16 /* internal public module error */#define DSVC_MODULE_LOAD_ERR 17 /* error loading public module */#define DSVC_MODULE_UNLOAD_ERR 18 /* error unloading public module */#define DSVC_MODULE_CFG_ERR 19 /* module configuration failure */

#define DSVC_SYNCH_ERR 20 /* error in synchronization protocol */


#define DSVC NO LOCKMGR 21 /* cannot contact lock manager */

Generic ErrorCodes


42/52

#define DSVC_NO_LOCKMGR 21 / cannot contact lock manager /#define DSVC_NO_LOCATION 22 /* location nonexistent */#define DSVC_BAD_CONVER 23 /* malformed/missing CONVER setting */#define DSVC_NO_TABLE 24 /* table does not exist */#define DSVC_TABLE_EXISTS 25 /* table already exists */#define DSVC_NERR (DSVC_TABLE_EXISTS + 1)


4C H A P T E R 4


43/52

Code Samples and Testing

This chapter includes some segments o code that illustrate proper use o the API unctions.


Code Templates on page 43 Testing the Public Module on page 49

Code TemplatesThis section provides templates that show in generalhow you might use the API unctions.

Note Download the source code or Sun's ASCII les data store (ds_SUNWfiles)inthe

developer pages on Sun's web site (http://www.sun.com/developer). The source code or themodule may prove invaluable in writing your own module.

General API Functions

This template uses the general API unctions status(), version(),and mklocation().

EXAMPLE41 general.c

* Copyright (c) 2000 by Sun Microsystems, Inc. /** Copyright (c) 2000 by Sun Microsystems, Inc.* All rights reserved.*/

#pragma ident "@(#)general.c 1.15 00/08/16 SMI"

/*

* This module contains the public APIs for status, version, and mklocation.*/

4C H A P T E R 4

43

EXAMPLE 41 general.c (Continued)

CodeTemplates


44/52

#include

#include #include #include #include

/** This API function instructs the underlying datastore to return its* general status. If the "location" argument is non-NULL, the function* validates the location for the data store containers (is it formed* correctly for the data store, and does it exist).*/

intstatus(const char *location){

return (DSVC_UNSUPPORTED);}

/** Return the data store API version supported by this module. This version* was implemented to support version 1 of the API.*/

intversion(int *vp){

*vp = DSVC_PUBLIC_VERSION;return (DSVC_SUCCESS);

}

/** Create the datastore-specific "location" if it doesnt already exist.* Containers will ultimately be created there.*/

intmklocation(const char *location){


dhcptabAPI Functions

This template illustrates unctions that are used with the dhcptab container.

EXAMPLE42 dhcptab.c

/** Copyright (c) 1998-2000 by Sun Microsystems, Inc.* All rights reserved.*/

#pragma ident "@(#)dhcptab.c 1.12 00/08/16 SMI"


EXAMPLE 42 dhcptab.c (Continued)

CodeTemplates


45/52

/** This module contains the public API functions for managing the dhcptab

* container.*/

#include #include #include #include #include

/** List the current number of dhcptab container objects located at* "location" in "listppp". Return number of list elements in "count".* If no objects exist, then "count" is set to 0 and DSVC_SUCCESS is* returned.** This function will block waiting for a result, if the underlying* data store is busy.*/

intlist_dt(const char *location, char ***listppp, uint32_t *count){


/** Creates or opens the dhcptab container in "location" and initializes* "handlep" to point to the instance handle. When creating a new dhcptab,* the callers identity is used for owner/permissions. Performs any* initialization needed by data store.*/

intopen_dt(void **handlep, const char *location, uint32_t flags)

{return (DSVC_UNSUPPORTED);

}

/** Frees instance handle, cleans up per instance state.*/

intclose_dt(void **handlep){


/** Remove dhcptab container in "location" from data store. If the underlying* data store is busy, this function will block.*/

intremove_dt(const char *location){

return (DSVC_UNSUPPORTED);

}

Chapter 4 Code Samples and Testing 45


CodeTemplates


46/52

/*

* Searches the dhcptab container for instances that match the query* described by the combination of query and targetp. If the partial* argument is true, then lookup operations that are unable to* complete entirely are allowed (and considered successful). The* query argument consists of 2 fields, each 16 bits long. The lower* 16 bits selects which fields {key, flags} of targetp are to be* considered in the query. The upper 16 bits identifies whether a* particular field value must match (bit set) or not match (bit* clear). Bits 2-15 in both 16 bit fields are currently unused, and* must be set to 0. The count field specifies the maximum number of* matching records to return, or -1 if any number of records may be* returned. The recordsp argument is set to point to the resulting* list of records; if recordsp is passed in as NULL then no records* are actually returned. Note that these records are dynamically* allocated, thus the caller is responsible for freeing them. The* number of records found is returned in nrecordsp; a value of 0* means that no records matched the query.*/

intlookup_dt(void *handle, boolean_t partial, uint32_t query, int32_t count,

const dt_rec_t *targetp, dt_rec_list_t **recordsp, uint32_t *nrecordsp)


}

/** Add the record pointed to by "addp" to from the dhcptab container* referred to by the handle. The underlying public module will set* "addps" signature as part of the data store operation.*/

intadd_dt(void *handle, dt_rec_t *addp)


}

/** Atomically modify the record "origp" with the record "newp" in the* dhcptab container referred to by the handle. "newps" signature will* be set by the underlying public module. If an update collision* occurs, either because "origps" signature in the data store has changed* or "newp" would overwrite an existing record, DSVC_COLLISION is* returned and no update of the data store occurs.*/

intmodify_dt(void *handle, const dt_rec_t *origp, dt_rec_t *newp){


/** Delete the record referred to by dtp from the dhcptab container* referred to by the handle. If "dtps" signature is zero, the

* caller is not interested in checking for collisions, and the record



CodeTemplates


47/52

* should simply be deleted if it exists. If the signature is non-zero,* and the signature of the data store version of this record do not match,

* an update collision occurs, no deletion of matching record in data store* is done, and DSVC_COLLISION is returned.*/

intdelete_dt(void *handle, const dt_rec_t *dtp){


DHCP Network Container API FunctionsThis template illustrates unctions used with the the DHCP network containers.

EXAMPLE43 dhcp_network.c

/** Copyright (c) 1998-2000 by Sun Microsystems, Inc.* All rights reserved.

*/

#pragma ident "@(#)dhcp_network.c 1.12 00/08/16 SMI"

/** This module contains public API functions for managing dhcp network* containers.*/

#include #include

#include #include #include

/** List the current number of dhcp network container objects located at* "location" in "listppp". Return number of list elements in "count".* If no objects exist, then "count" is set to 0 and DSVC_SUCCESS is* returned.** This function will block if the underlying data service is busy or is* otherwise unvailable.*/

intlist_dn(const char *location, char ***listppp, uint32_t *count){


/** Creates or opens the dhcp network container "netp" (host order) in

*"

location"

and initializes"

handlep"

to point to the instance handle.


EXAMPLE 43 dhcp_network.c (Continued)

CodeTemplates


48/52

* Performs any initialization needed by data store. New containers are* created with the identity of the caller.

*/intopen_dn(void **handlep, const char *location, uint32_t flags,

const struct in_addr *netp){


/** Frees instance handle, cleans up per instance state.*/

intclose_dn(void **handlep){


/** Remove DHCP network container "netp" (host order) in location.* This function will block if the underlying data service is busy or* otherwise unavailable.

*/intremove_dn(const char *location, const struct in_addr *netp){


/** Searches DHCP network container for instances that match the query* described by the combination of query and targetp. If the partial* argument is true, then lookup operations that are unable to

* complete entirely are allowed (and considered successful). The* query argument consists of 2 fields, each 16 bits long. The lower* 16 bits selects which fields {client_id, flags, client_ip,* server_ip, expiration, macro, or comment} of targetp are to be* considered in the query. The upper 16 bits identifies whether a* particular field value must match (bit set) or not match (bit* clear). Bits 7-15 in both 16 bit fields are currently unused, and* must be set to 0. The count field specifies the maximum number of* matching records to return, or -1 if any number of records may be* returned. The recordsp argument is set to point to the resulting* list of records; if recordsp is passed in as NULL then no records* are actually returned. Note that these records are dynamically* allocated, thus the caller is responsible for freeing them. The* number of records found is returned in nrecordsp; a value of 0 means* that no records matched the query.*/

intlookup_dn(void *handle, boolean_t partial, uint32_t query, int32_t count,

const dn_rec_t *targetp, dn_rec_list_t **recordsp, uint32_t *nrecordsp){

return (DSVC_UNSUPPORTED);

}


EXAMPLE 43 dhcp_network.c (Continued)

Testing the Public Module


49/52

/*

* Add the record pointed to by "addp" to from the dhcp network container* referred to by the handle. The underlying public module will set* "addps" signature as part of the data store operation.*/

intadd_dn(void *handle, dn_rec_t *addp){


/** Atomically modify the record "origp" with the record "newp" in the dhcp* network container referred to by the handle. "newps" signature will* be set by the underlying public module. If an update collision* occurs, either because "origps" signature in the data store has changed* or "newp" would overwrite an preexisting record, DSVC_COLLISION is* returned and no update of the data store occurs.*/

intmodify_dn(void *handle, const dn_rec_t *origp, dn_rec_t *newp){


/** Delete the record pointed to by "pnp" from the dhcp network container* referred to by the handle. If "pnps" signature is zero, the caller* is not interested in checking for collisions, and the record should* simply be deleted if it exists. If the signature is non-zero, and the* signature of the data store version of this record do not match, an* update collision occurs, no deletion of any record is done, and* DSVC_COLLISION is returned.

*/intdelete_dn(void *handle, const dn_rec_t *pnp){


Testing the Public ModuleSee http://www.sun.com/developer or some downloadable test suites that may help you intesting your public module.



50/52

50


51/52

Index

Aaccess to data store containers, synchronizing, 20

Application/Service Layer, 14

Ddata access layers

denition o, 14diagram, 14

data store containername, 23provided with Solaris DHCP, 17record ormats, 23upgrading, 24

dhcpmgr, integrating new data store with, 25dhcpsvc.conf conguration le, 14dhcptab container

unctions, 32internal orm, 23name, 23

dn_rec_t and dt_rec_t data structures, 21dn_sig and dt_sig update signatures, 21dsvc_synchtypevariable, 21dsvclockd daemon, 21dsvclockd le, 21duplicate container records, 23

FFramework Conguration Layer, 15

GgetAdditional() unction, 26

getComponent() unction, 25getDescription() unction, 25getPath() unction, 26

Hhandles, 19

JJavaBeans, or public module, 25

Llibdhcpsvc.so library, 14, 21

Mmanagement bean

unctions, 25packaging requirements, 26

modular ramework, 13

Nname, public module, 22

51

network containerunctions, 37

Index


52/52

internal orm, 23name, 23

Ppublic module, name ormat, 22

Rrecord update collisions, 21

SService Provider Layer, list o API unctions, 16synchronizing access to data store containers, 20

Uupgrading, containers, 24


Date post:	06-Apr-2018
Category:	Documents
Upload:	shahmat-dahlan
View:	233 times
Download:	0 times

806-6829 - Solaris DHCP Service Developer's Guide

Documents