Solaris ISP Server 2.0 Administration Guide

Chapter 6 Solaris ISP Server Directory Schema

Solaris ISP ServerTM 2.0 extends the standard schema defined in SunTM Directory Services. The base schema is defined in Chapter 8, "Configuring the Directory Schema," of the Sun Directory Services 3.1 Administration Guide. Extensions to the base schema, both object classes and attributes, are discussed in this chapter.


Note -

The schema defined by Solaris ISP Server is unstable in this release of the product. Object class and attribute definitions that are a part of the schema extension may change without warning in future releases. See "Avoiding Schema Dependence" for guidelines on avoiding schema dependence in your code.


This chapter includes the following topics:

Maintaining the Schema

In general, you should not change existing object classes or attributes in the schema, but use or add to them for your purposes. If you change an attribute or object class so that the Solaris ISP Server software cannot use it, you may have to reinstall the directory. In this case, any data entries not backed up will be lost. For information on backing up the directory, see the Sun Directory Services manual pages for ldbmcat(1M) and ldif2ldbm(1M).

If you decide to add to the schema, refer to Chapter 8, "Configuring the Directory Schema," of the Sun Directory Services 3.1 Administration Guide for complete details.

What to Back Up

To ensure the integrity of the directory, you should periodically back up the schema configuration files. Certainly, you should back up the schema before starting work to extend it for your own uses.

As discussed in detail in Chapter 4, "Configuring Directory Services," of the Sun Directory Services 3.1 Administration Guide, the following files are critical for directory services function:

Copies of these files are stored in three places in the system:

Before starting any work on the schema, back up the configuration files in /etc/opt/SUNWconn/ldap/current and those in /etc/opt/SUNWconn/ldap/previous. When you edit the files through dsadmintool or restart the daemon, Sun Directory Services copies the unedited files in /etc/opt/SUNWconn/ldap/current to /etc/opt/SUNWconn/ldap/previous. It does this only once per editing session, (until you restart dsservd). If you are making many changes to the schema, you may want to make manual backups of your changes as you work.

Backup information is presented in detail in Chapter 4, "Configuring Directory Services," of the Sun Directory Services 3.1 Administration Guide.

Restoring the Schema

To restore your directory services configuration to a previous version, stop dsservd, replace the desired configuration files in /etc/opt/SUNWconn/ldap/current, and restart the daemon. Step-by-step information is presented in Chapter 4, "Configuring Directory Services," of the Sun Directory Services 3.1 Administration Guide.

Restoring the Solaris ISP Server Schema

When Solaris ISP Server is installed, the original schema configuration files are backed up at /etc/opt/SUNWisp/ldap/sunds/default. These files were customized at installation with your root domain and administrator information. If you are working on the schema, and arrive at a situation where Solaris ISP Server does not work, restore the default schema as follows:

  1. Log into the machine where the directory services is running.

  2. Give yourself root access.

  3. Stop the directory services server, by entering:# /etc/init.d/dsserv stop


    Note -

    You can also stop and start the server through its administration console.


  4. Copy each of the configuration files from the default to the current directory:


    % cp /etc/opt/SUNWisp/ldap/sunds/default/dsserv.conf \
    /etc/opt/SUNWconn/ldap/current/dsserv.conf
    
    % cp /etc/opt/SUNWisp/ldap/sunds/default/SUNWisp.dsserv.at.conf \
    /etc/opt/SUNWconn/ldap/current/SUNWisp.dsserv.at.conf
    
    % cp /etc/opt/SUNWisp/ldap/sunds/default/SUNWisp.dsserv.oc.conf \
    /etc/opt/SUNWconn/ldap/current/SUNWisp.dsserv.oc.conf
    
    % cp /etc/opt/SUNWisp/ldap/sunds/default/dsserv.acl.conf \
    /etc/opt/SUNWconn/ldap/current/dsserv.acl.conf
    
    % cp /etc/opt/SUNWisp/ldap/sunds/default/mapping/radius.mapping \
    /etc/opt/SUNWconn/ldap/current/mapping/radius.mapping
    
  5. Start the directory services server by entering:# /etc/init.d/dsserv start

Avoiding Schema Dependence

Because the Solaris ISP Server schema is still evolving, developing code that depends on it could make your program hard to maintain. Future releases of the product may have schema changes that are not compatible with the current schema. Any program that uses schema-dependent code, such as hard-coded object class or attribute names or assuming certain directory information tree structure, would have to be modified and recompiled with the new schema specifics.

To avoid this problem as much as possible, isolate any schema specifics in your code. When you need a specific detail, such as the distinguished name of a configuration entry, use the ISP Directory Information API to get it. If you need information that IDIA does not provide, use the LDAP client library and isolate the functionality in separate functions or classes in your code and reuse them.

ISP Directory Information API

The ISP Directory Information API provides C and Java programming language access to the directory services. The functions return information specific to the directory information tree (DIT) used by Solaris ISP Server. By default, the header file is located at /opt/SUNWisp/include/isp_dir_api.h, and the library is located at /opt/SUNWisp/lib/libispdir.so.1. The Java package is com.sun.isp.idia.

The directory information API includes the following:

ispGetLdapInfo(3X)

This C functions provides the distinguished name and password for binding to the LDAP server with access to a particular region of the directory information tree (DIT).

ispGetLdapServers(3X)

This C function provides the names and port numbers of LDAP directory servers configured on the network.

ispGetTopDn(3X)

This C function provides the distinguished name of the root domain (top-level domain entry in the DIT, under which Solaris ISP Server information is stored).

ispLdapService(3X)

This Java class provides information on LDAP servers configured on the network. Various class methods return the root domain entry in the DIT and distinguished names and passwords for binding to the directory.

LDAP Client Library

The LDAP client library is an implementation of the LDAP v3 standard. It provides support for client applications communicating with an LDAP server such as Sun Directory Services.

By default, the header files are located at /usr/include/ldap.h and /usr/include/lber.h, and the library is located at /usr/lib/libldap.so.3. The LDAP client library man pages are located in /usr/share/man, in section 3.

Solaris ISP Server Object Classes

This section contains a list of the object classes added to the base schema to support Solaris ISP Server. Attributes listed as mandatory must have a value entered when the entry is created. Object classes are listed in alphabetical order.

ispAdministrator Class

Purpose: Defines an entry representing an administrator of ISP services and networks. The ispAdministrator's relative distinguished name is the commonName attribute and its value. Its superior object is ispSubscriber.

Table 6-1 ispAdministrator Attributes
 Attribute name Mandatory? Schema Purpose
associatedDomain No Base The domain with which this administrator is associated. Reserved for future Solaris ISP Server functionality.
commonName Yes Base The name of the administrator described by the entry, in the form Firstname Lastname (userid).
description No Base An arbitrary description of the administrator.
gidNumber No Base A UNIX group-ID. Specifies the gid of files created via FTP by this user.
homeDirectory No Base The file system location of the home directory of the administrator described by the entry. (Not used by Solaris ISP Server.)
ispAdministeredService No Extension The distinguished names of services this administrator is authorized to manage.
ispContentDirectory No ExtensionA directory location where content belonging to the administrator is located. For virtually-hosted FTP or Web services, the path to user content relative to the ispRootDirectory.
labeledURI  No Base The Uniform Resource Identifier and label associated with the Web page of this administrator.
mail No Base The advertised electronic mail address of the administrator.
objectClass Yes BaseThe object class of the entry (ispAdministrator).
ou No BaseThe organizational unit to which the entry belongs. In this release of Solaris ISP Server, the Administrator node under the root domain.
surname Yes Base The family name of the administrator
userCertificate No Base A certificate containing the public key of the administrator.
userid Yes Base The login name of the administrator.
userPassword Yes Base The password of the administrator.
uidNumber No Base A UNIX user-ID. Specifies the uid of files created via FTP by this user.

ispManagedService Class

Purpose: Defines an entry representing an ISP service that is managed by Sun Internet Administrator. This object class is reserved for use by Sun Internet Administrator. The ispManagedService's relative distinguished name is the host attribute and its value.

Table 6-2 ispManagedService Attributes
 Attribute name Mandatory? Schema Purpose
associatedName No Base The distinguished name of the top-level service entry for this service.
commonName No Base The user-friendly name of a service, for display in the GUI of Sun Internet Administrator
host Yes Base The fully-qualified name of the host where this service is installed.
ispCategory No BaseThe type of user interface supported by this service. See the ispCategory attribute section for details.
ispImageFile No Extension The name of a GIF image file containing the icon for this service.
ispServiceLocation No Extension The path to the X-based administration application for this service.
ispParameterizedOperation No Extension Information on a supported command-line utility that accepts parameters.
ispServlets No Extension The fully-qualified Java class name of a servlet used in this service's administration user interface.
ispServletClasspath No Extension The Java classpath for classes required by this service's administration user interface.
ispSupportedOperation No Extension Information on a supported command-line utility that accepts no parameters.
ispVersion No Extension The release number (major.minor) of the service described by the entry.
labeledURI  No Base The path to the main GUI page of a service. For a 3-tier service, enter a path relative to the document root. For a 2-tier service, enter the complete URL.
objectClass Yes BaseThe object class of the entry (ispManagedService).

ispService Class

Purpose: Defines an entry representing a Solaris ISP Server software component. The ispService's relative distinguished name is the ispVersion attribute and its value.

Table 6-3 ispService Attributes
 Attribute name Mandatory? Schema Purpose
associatedDomain No Base The domain with which this service is associated.
commonName Yes Base The name of the service (not used in Solaris ISP Server).
description No Base An arbitrary description of the service.
host No Base The fully-qualified name of the host where the service is installed.
ispDirectoryRoot No Extension A directory prefix to a location on the file system where a domain's content is virtually-hosted. Used by Sun Internet FTP Server and Sun WebServer when in a virtual host configuration.
ispPrivateData No Extension Software component password information for use by Sun Internet Administrator. This attribute is protected by ACLs from access by a user other than the directory root and Sun Internet Administrator.
ispServiceContext No Extension A CORBA naming context used by Sun Internet FTP Server and Sun Internet News Server.
ispServiceLocation No Extension A CORBA stringified object reference to the service administration server. (Used by Sun Internet FTP Server and Sun Internet News Server.)
ispSupplementaryInformation No Extension Arbitrary information about the service. Reserved for Solaris ISP Server service-specific needs.
ispVersion Yes Extension The release number (major.minor) of the service described by the entry.
labeledURI  No Base The path to the servlets for a three-tier GUI.
mail No Base The advertised electronic mail address of the user. Not used by Solaris ISP Server.
objectClass Yes BaseThe object class of the entry (ispService).
userCertificate No Base A certificate containing the public key of the user.
userPassword No Base The password of the entry, used for binding to the directory

ispSubscriber Class

Purpose: Defines an entry representing a subscriber (customer) of the ISP. The ispSubscriber's relative distinguished name is the commonName attribute and its value. Its superior object is inetOrgPerson.

If you are using the RADIUS server that comes with Sun Directory Services, overlay the ispSubscriber objects with the remoteUser object class.

Table 6-4 ispSubscriber Attributes
 Attribute name Mandatory? Schema Purpose
associatedDomain No Base The domain with which this subscriber is associated.
commonName Yes Base The name of the subscriber described by the entry, in the form Firstname Lastname (userid).
gidNumber No Base A UNIX group-ID. Specifies the gid of files created via FTP by this user.
homeDirectory No Base The file system location of the home directory of the subscriber described by the entry. (Not used by Solaris ISP Server.)
host No Base The fully-qualified name of the host. Not used by Solaris ISP Server.
ispAuthorizedServices No Extension The distinguished names of services the subscriber is authorized to use.
ispContentDirectory No ExtensionA directory location where content belonging to a subscriber is located. For virtually-hosted FTP and Web services, the path relative to the ispRootDirectory.
labeledURI  No Base The Uniform Resource Identifier and label associated with the Web page of this subscriber.
mail No Base The advertised electronic mail address of the subscriber.
objectClass Yes BaseThe object class of the entry (ispSubscriber).
ou No BaseThe organizational unit to which the subscriber belongs (in Solaris ISP Server, the People node under a domain entry).
surname Yes Base The family name of the subscriber.
uidNumber No Base A UNIX user-ID. Specifies the uid of files created via FTP by this user.
userCertificate No Base A certificate containing the public key of the subscriber.
userid Yes Base The login name of the subscriber.
userPassword Yes Base The password of the subscriber.

Solaris ISP Server Attributes

This section describes the attributes used by object classes added to the basic schema for Solaris ISP Server. Some of these attributes are a part of the base schema, but are included here for ease of use. Attributes created for the Solaris ISP Server schema extension begin with "isp."

Attributes defined in the schema have one of the following syntaxes:

The following list presents attributes in alphabetical order.

associatedDomain Attribute

Summary: cis, multi-valued, base schema

Purpose: Specifies the domain with which the object described by the entry is associated. For the OSI tree entry of a domain, must contain the name (in dot notation, for example, eng.sun.com) of the corresponding DC tree entry.

associatedName Attribute

Summary: dn, base schema

Purpose: Specifies the distinguished name of an entry associated with this entry. For the DC tree entry of a domain, must contain the distinguished name of the corresponding OSI tree entry.

commonName Attribute

Alternate name: cn

Summary: cis, multi-valued, base schema

Purpose: Specifies the full name of the object described by the entry.

Subscriber and administrator entries use the form Firstname Lastname (uid). For example, user John Smith who uses the login name jsmith would have an entry in the directory. Its commonName attribute would contain the value John Smith (jsmith).

The ispManagedService object class uses this attribute for the user-friendly name displayed in the Sun Internet Administrator GUI.

description Attribute

Summary: cis, multi-valued, base schema

Purpose: Specifies an arbitrary description of the entry object.

gidNumber Attribute

Summary: long, single-valued, base schema

Purpose: Specifies the UNIX group-ID of files created via FTP by this user.

homeDirectory Attribute

Summary: ces, single-valued, base schema

Purpose: Specifies the file system location of the home directory of the user described by the entry. This attribute is not used by Solaris ISP Server, but is left for general information required by the customer.

host Attribute

Summary: cis, multi-valued, base schema

Purpose: Specifies the name of the machine associated with or managed by the object described by the entry. When used with Solaris ISP Server object entries, the host attribute must contain the fully-qualified host name.

ispAdministeredService Attribute

Summary: dn, multi-valued, Solaris ISP Server schema extension

Purpose: Specifies the services (by distinguished names of the top-level service entries) that an administrator can manage. The top-level entry for a service is an ispService object under the root domain entry. For example, under ou=services,o=sun,c=us where sun.com is the root domain entry.

ispAuthorizedServices Attribute

Summary: dn, multivalued, Solaris ISP Server schema extension

Purpose: Specifies the services (by distinguished name) that an ispSubscriber is authorized to use.

ispCategory Attribute

Summary: cis, single-valued, Solaris ISP Server schema extension

Purpose: Specifies the category of graphical user interface supported by the service described by the entry. Acceptable values are:

ispContentDirectory Attribute

Summary: ces, single-valued, Solaris ISP Server schema extension

Purpose: Specifies a directory location (which may be distinct from that in the homeDirectory attribute) where content belonging to a user is located. Used by ispAdministrator and ispSubscriber classes. For a user with virtually-hosted FTP services, must contain the path (relative to the ispDirectoryRoot of the domain) to the user's FTP content.

ispDirectoryRoot Attribute

Summary: ces, single-valued, Solaris ISP Server schema extension

Purpose: Specifies a root directory for an ISP service, usually on a per-domain basis.

ispImageFile Attribute

Summary: cis, single-valued, Solaris ISP Server schema extension

Purpose: Specifies the name of a file containing the image described by the entry. The ispManagedService object class uses this attribute to specify its GIF-format icon file.

ispPrivateData Attribute

Summary: ces, single-valued, Solaris ISP Server schema extension

Purpose: Specifies software component password information used by Sun Internet Administrator. This attribute is protected by ACLs from access by users other than the Sun Directory Services root administrator.

ispServiceContext Attribute

Summary: ces, single-valued, Solaris ISP Server schema extension

Purpose: Specifies a service context for use by an ISP service. For Sun Internet FTP Server and Sun Internet News Server, this is a CORBA naming context.

ispServiceLocation Attribute

Summary: ces, single-valued, Solaris ISP Server schema extension

Purpose: Specifies the location of the ispService object described by the entry.

Sun Internet FTP Server and Sun Internet News Server use this attribute in an ispService object to store a CORBA stringified object reference to their administration servers. Sun Internet Administrator uses this attribute in an ispManagedService object to store the path to an X-based user interface application.

ispServlets Attribute

Summary: ces, multivalued, Solaris ISP Server schema extension

Purpose: Specifies the fully-qualified Java class name of a servlet used in an ispManagedService's administration user interface. For each servlet used, assign an ispServlets attribute with the following value:

  1. The path to the servlet, relative to the document root of the administration Web server (part of Sun Internet Administrator)

  2. The fully-qualified Java class name of the servlet

  3. Any required servlet arguments, listed by name and value

ispServletClasspath Attribute

Summary: ces, single-valued, Solaris ISP Server schema extension

Purpose: Specifies the Java classpath for classes required by an ispManagedService's administration user interface. A Java classpath may contain several paths; separate them with colons (:).

ispParameterizedOperation Attribute

Summary: ces, multivalued, Solaris ISP Server schema extension

Purpose: Specifies information about a command-line function that takes parameters. For an ispManagedService object, three space-delimited fields of information are required:

  1. The complete path to the command-line utility

  2. The complete path to a help file for the utility, or NONE if there is no help information for the utility.

  3. An arbitrary string, containing the space-delimited parameters required by the utility. If parameters are accepted from the user on the command line, this field holds the string SOME.

ispSupplementaryInformation Attribute

Summary: cis, multivalued, base schema

Purpose: Holds additional information concerning the object described by the entry. In object classes that extend the base schema, this attribute is reserved for Solaris ISP Server service-specific needs.

ispSupportedOperation Attribute

Summary: ces, multivalued, Solaris ISP Server schema extension

Purpose: Stores information on a supported command-line utility that accepts no parameters. For an ispManagedService object, three space-delimited fields of information are required:

  1. The complete path to the command-line utility

  2. The complete path to a help file for the utility, or NONE if there is no help information for the utility.

  3. The string NONE.

ispVersion Attribute

Summary: ces, single-valued, Solaris ISP Server schema extension

Purpose: Specifies the release version of the ispService object described by this entry. Solaris ISP Server uses the form major.minor for the version attribute.

labeledURI Attribute

Alternate name: labeledURL

Summary: ces, multi-valued, base schema

Purpose: Specifies a Uniform Resource Identifier (URI) and label associated with the object described by the entry.

mail Attribute

Alternate name: preferredRfc822Originator

Summary: cis, multi-valued, base schema

Purpose: Specifies the advertised electronic mail address, in RFC822 format, of the object described by the entry. Sun Internet FTP Server uses this attribute as an error-reporting address.

objectClass Attribute

Summary: cis, multivalued, base schema

Purpose: Specifies the object class of the type of entry.

ou Attribute

Alternate name: organizationUnitName

Summary: cis, base schema

Purpose: Specifies the name of the organization unit to which the object described by the entry belongs.

surname Attribute

Alternate name: sn

Summary: cis, base schema

Purpose: Specifies the surname of the person described by the entry.

uidNumber Attribute

Summary: long, single-valued, base schema

Purpose: Specifies the UNIX user-ID of files created via FTP by this user.

userCertificate Attribute

Summary: bin, base schema

Purpose: Specifies a certificate containing the public key of the user described by the entry.

userid Attribute

Alternate name: uid

Summary: cis, multi-valued, base schema

Purpose: Specifies the login name of the user described by the entry.

userPassword Attribute

Summary: protected, multi-valued, base schema

Purpose: Specifies the password for the entity described by the entry.

Schema Changes for SunTM Internet Mail Server

If you configure your Solaris ISP Server installation to interoperate with Sun Internet Mail Server, a few additions are made to your schema. The schemas of both the main directory and the slave installation that supports mail must be identical. This new object class and its attributes support calendaring, but change no functionalty on the Solaris ISP Server side.

IMCalendarUser Object Class

Purpose: Defines an entry that stores calendaring information.

Table 6-5 IMCalendarUser Attributes
 Attribute name Mandatory? Schema Purpose
IMCalendarHost Yes SIMS The fully-qualified host name (the machine where the calendar server is running).
IMCalendarName No SIMS The name of the calendar.
objectClass Yes BaseThe object class of the entry (IMCalendarUser, but there may be others)
userid Yes Base The login name of the calendar user.
userPassword Yes Base The calendar user's password (shared with SIMS/IMAP login).

IMCalendarHost Attribute

Summary: cis, single-valued, SIMS schema

Purpose: The fully qualified calendar server host name.

IMCalendarName Attribute

Summary: ces, single-valued, SIMS schema

Purpose: The name of the user's calendar.