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.
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:
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.
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:
dsserv.conf holds the main configuration information.
dsserv.oc.conf holds the object class definitions.
dsserv.at.conf holds the attribute definitions.
dsserv.acl.conf holds access control information.
SUNWisp.dsserv.at.conf holds the attribute definitions for Solaris ISP Server schema extensions.
SUNWisp.dsserv.oc.conf holds the object class definitions for Solaris ISP Server schema extensions.
Copies of these files are stored in three places in the system:
/etc/opt/SUNWconn/ldap/current holds the current configuration files.
/etc/opt/SUNWconn/ldap/default holds the default configuration files that were installed with the software. (These files are read-only.)
/etc/opt/SUNWconn/ldap/previous holds the previous configuration files.
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.
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.
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:
Log into the machine where the directory services is running.
Give yourself root access.
Stop the directory services server, by entering:# /etc/init.d/dsserv stop
You can also stop and start the server through its administration console.
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 |
Start the directory services server by entering:# /etc/init.d/dsserv start
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.
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:
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).
This C function provides the names and port numbers of LDAP directory servers configured on the network.
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).
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.
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.
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.
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 AttributesAttribute 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 | Extension | A 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. |
No | Base | The advertised electronic mail address of the administrator. | |
objectClass | Yes | Base | The object class of the entry (ispAdministrator). |
ou | No | Base | The 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. |
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 AttributesAttribute 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 | Base | The 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 | Base | The object class of the entry (ispManagedService). |
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 AttributesAttribute 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. |
No | Base | The advertised electronic mail address of the user. Not used by Solaris ISP Server. | |
objectClass | Yes | Base | The 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 |
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 AttributesAttribute 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 | Extension | A 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. |
No | Base | The advertised electronic mail address of the subscriber. | |
objectClass | Yes | Base | The object class of the entry (ispSubscriber). |
ou | No | Base | The 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. |
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:
bin: binary
ces: case-exact string
A case-sensitive alphanumeric string.
cis: case-ignore string
An alphanumeric string, not case-sensitive.
dn: distinguished name
protected: encrypted
A value that has been encrypted using crypt
int or long: integer
tel: telephone number
utctime: UTC time
The following list presents attributes in alphabetical order.
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.
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.
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.
Summary: cis, multi-valued, base schema
Purpose: Specifies an arbitrary description of the entry object.
Summary: long, single-valued, base schema
Purpose: Specifies the UNIX group-ID of files created via FTP by this user.
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.
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.
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.
Summary: dn, multivalued, Solaris ISP Server schema extension
Purpose: Specifies the services (by distinguished name) that an ispSubscriber is authorized to use.
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:
2tier, indicating that the user interface is Web-based and uses the two-tier architecture supported by Sun Internet Administrator.
3tier, indicating that the user interface is Web-based and uses the three-tier architecture supported by Sun Internet Administrator.
CLI, indicating that the user interface is a command-line utility.
X, indicating that the user interface is an X-based program.
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.
Summary: ces, single-valued, Solaris ISP Server schema extension
Purpose: Specifies a root directory for an ISP service, usually on a per-domain basis.
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.
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.
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.
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.
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:
The path to the servlet, relative to the document root of the administration Web server (part of Sun Internet Administrator)
The fully-qualified Java class name of the servlet
Any required servlet arguments, listed by name and value
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 (:).
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:
The complete path to the command-line utility
The complete path to a help file for the utility, or NONE if there is no help information for the utility.
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.
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.
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:
The complete path to the command-line utility
The complete path to a help file for the utility, or NONE if there is no help information for the utility.
The string NONE.
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.
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.
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.
Summary: cis, multivalued, base schema
Purpose: Specifies the object class of the type of entry.
Alternate name: organizationUnitName
Summary: cis, base schema
Purpose: Specifies the name of the organization unit to which the object described by the entry belongs.
Alternate name: sn
Summary: cis, base schema
Purpose: Specifies the surname of the person described by the entry.
Summary: long, single-valued, base schema
Purpose: Specifies the UNIX user-ID of files created via FTP by this user.
Summary: bin, base schema
Purpose: Specifies a certificate containing the public key of the user described by the entry.
Alternate name: uid
Summary: cis, multi-valued, base schema
Purpose: Specifies the login name of the user described by the entry.
Summary: protected, multi-valued, base schema
Purpose: Specifies the password for the entity described by the entry.
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.
Purpose: Defines an entry that stores calendaring information.
Table 6-5 IMCalendarUser AttributesAttribute 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 | Base | The 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). |
Summary: cis, single-valued, SIMS schema
Purpose: The fully qualified calendar server host name.
Summary: ces, single-valued, SIMS schema
Purpose: The name of the user's calendar.