test

Solaris for ISPs Administration Guide

Chapter 5 Using Directory Services

SolarisTM for ISPsTM uses SunTM Directory Services to store component software information and login information for SunTM Internet AdministratorTM and for some services. This information includes standard object classes and newly-defined objects that support Solaris for ISPs functionality.

This chapter provides information on the Solaris for ISPs information tree structure, on making entries in the tree from the command line, and on required access controls. For information on the schema extension itself, see Chapter 6, Solaris for ISPs Directory Services Schema.

Sun Directory Services provides the following tools for using and administering the directory:

The Sun Directory Services books, Sun Directory Services 3.1 Administration Guide and Sun Directory Services 3.1 User's Guide, include complete information on starting and using these tools. They are provided in AnswerBook2 format on the product CD-ROM. The command-line programs are documented in man pages in section 1 (/opt/SUNWconn/man).

Solaris for ISPs Directory Structure

Solaris for ISPs requires a specific structure in the directory information tree (DIT), which is created during installation and configuration. The required structure consists of two naming contexts, referred to as the Open Systems Interconnection (OSI) tree and the Domain Component (DC) tree. Portions of the two trees are parallel. This parallel structure facilitates mapping of domain names from a DNS request through the DC tree to the actual content entries in the OSI tree.

OSI Tree Structure

The OSI tree contains the actual entries for Solaris for ISPs, its component services, administrators of those services, and subscribers to the services. The required structure is shown in Figure 5-1.

Figure 5-1 Solaris for ISPs OSI Tree

Graphic

In the OSI tree, the entry for the domain sun.com is represented by the entry with the distinguished name o=sun,c=us. This entry is called the root domain, and represents the Solaris for ISPs customer's business. You specify the name of the root domain during installation of the directory services.

Beneath the root domain are four required organizationalUnit entries:

People, Groups, and Services nodes are required under each domain entry you define. The Administrators node exists only under the root domain.

Figure 5-2 illustrates a typical set of entries under each organizational unit.

Figure 5-2 OSI Tree Entries

Graphic

The organizationalUnit entry eng is an example of a domain entry. This might be a corporate customer of the ISP, or anyone who has virtual domain hosting services with the ISP. Domains must have two entries: one here in the OSI tree and another in the DC tree for domain name mapping. See "Creating Domain Entries" for information on creating these two entries properly.

Domains, like the root domain, require certain organizationalUnit entries within them. As shown in Figure 5-3, People, Groups, and Services entries are also required in a domain below the root.

Figure 5-3 Domain Structure in the OSI Tree

Graphic

When creating a domain entry in the OSI tree, you must also create the entries for People, Groups, and Services. When you configure services for this domain, service entries are made under the Services organizational unit. Subscriber information for this domain forms ispSubscriber entries under the People organization unit.

Note -

Administrator entries are made only under the root domain in this version of Solaris for ISPs. These entries are created by Sun Internet Administrator when you specify them through the GUI.

DC Tree Structure

The DC (domain component) tree maps domain name format (for example, sun.com) to the distinguished name of the corresponding entry in the OSI tree. As shown in Figure 5-4, the DC is usually relatively flat and simpler than the OSI tree.

Figure 5-4 Solaris for ISPs DC Tree

Graphic

In Figure 5-4, the entry dc=sun,dc=com corresponds to the o=sun,c=us entry in the OSI tree. The eng domain here maps to the domain name server (DNS) form eng.sun.com.

For details on how to make the two domain entries, see "Creating Domain Entries".

Making Directory Entries from the Command Line

General information on how to create directory services entries is located in Chapter 5, "Loading and Maintaining Directory Information," in the Sun Directory Services 3.1 Administration Guide. This section presents instructions on how to create the specific entries required by Solaris for ISPs.

For information on how to create directory entries using the Deja tool, see the SunTM Internet AdministratorTM on-line help.

Creating Directory Entries: General Procedure

Sun Directory Services has the following command-line utilities for creating and modifying directory entries:

These directory services command-line utilities require root access. They are fully documented in reference manual pages (section 1).

Both ldapadd and ldapmodify can take input from the command line or from a specified file. Because information for an entry can be rather lengthy and complex, the sections that follow describe the form requiring a text file.

In each case, creating an entry (or entries) requires the following steps:

  1. Write a file specifying the entry or entries to be made in the directory. The format for this file is specified in the ldif(4) reference manual page.

  2. Obtain root access and create the entry using ldapadd, specifying the file with the entry information.

In every case, the form of the ldapadd command should be:

# ldapadd -D "BindDN" -w password -f file

Where the BindDN is the distinguished name (DN) for binding to the directory with write access to this part of the directory tree, and password the password for binding. Replace the file option with the name of the ldif file you have created.

Structure of an ldif(4) File

For each entry you add at the command line, you will create an ldif-format file to hold the information about the entry. These are simple text files with one or more directory entries each separated by a single blank line. Each entry has the structure: of the following example.

Note -

Only mandatory attributes are shown in the example. Most object classes have a number of optional attributes that may be set appropriately for your particular use of the entry.

dn: ou=wcgate1,ou=eng,o=sun,c=US 
ou: wcgate1 
associateddomain: wcgate1.eng.sun.com  
objectclass: organizationalUnit 
objectclass: domainRelatedObject

Where

dn

Indicates the distinguished name of the entry being created.

ou

Is the naming attribute of the entry being created. Common naming attributes include commonName, organizationalUnit (ou), and domainComponent (dc).

associatedDomain

Contains the domain name (in dot notation) of the corresponding entry in the DC tree. See "Solaris for ISPs Directory Structure" for information on how the OSI tree and the DC tree interact. See "Creating Domain Entries" for instructions on creating the two cross-referenced entries for a domain.

There may be many attribute:value pairs in this position, one per line.

objectClass

Is the object class (type) of the entry. There may be many objectClass entries; this example shows two.

For more detailed information on available object classes and attributes, see Chapter 6, Solaris for ISPs Directory Services Schema of this guide, and Chapter 8, "Configuring the Directory Schema," of the Sun Directory Services 3.1 Administration Guide.

Creating Domain Entries

To create a domain in the directory, you must create two parallel domain entries, one in the OSI tree and one in the DC tree, and then create the required organizationalUnit entries under the domain entry in the OSI tree.

To create the domain wcgate1 under eng.sun.com, perform the following steps:

  1. Edit a text file (for example, domain.ldif) and enter the data for the OSI tree entry:

    dn: ou=wcgate1,ou=eng,o=sun,c=US 
ou: wcgate1 
associateddomain: wcgate1.eng.sun.com 
objectclass: organizationalUnit 
objectclass: domainRelatedObject

    Note that the associatedDomain attribute of the entry contains the name of the DC tree entry in dot notation (DNS style).

  2. Add to domain.ldif the data for the DC tree entry:

    dn: dc=wcgate1,dc=eng,dc=sun,dc=com 
dc: wcgate1
associatedname: ou=wcgate1,ou=eng,o=sun,c=US 
description: DNS-to-DN Mapping for wcgate1.eng.sun.com 
labeleduri: ldap:///ou=wcgate1,ou=eng,o=sun,c=US??sub 
objectclass: domain 
objectclass: labeledURIObject

    Note that the associatedName attribute of the entry contains the distinguished name of the OSI tree entry. The labeledURI attribute contains the same information (as specified in RFC 2255).

  3. Add to domain.ldif the data for the required Services organizational unit entry:

    dn: ou=Services,ou=wcgate1,ou=eng,o=sun,c=US 
ou: Services 
objectclass: organizationalUnit

  4. Add to domain.ldif the data for the required People organizational unit entry:

    dn: ou=People,ou=wcgate1,ou=eng,o=sun,c=US 
ou: People 
objectclass: organizationalUnit

  5. Add to domain.ldif the data for the required Groups organizational unit entry:

    dn: ou=Groups,ou=wcgate1,ou=eng,o=sun,c=US 
ou: Groups 
objectclass: organizationalUnit

  6. Save and close domain.ldif.

  7. Obtain root access and add the entries to the directory with the following command, replacing the bind DN and password with your own:

    # ldapadd -D "cn=admin,o=sun,c=US" -w password -f domain.ldif

When your ldapadd is complete, the directory looks like Figure 5-5.

Figure 5-5 Directory Structure with a Domain Added

Graphic

Creating Subscriber Entries

Solaris for ISPs subscribers come in several varieties:

In the sections that follow, instructions are provided for building the complex subscriber entry by creating the simpler entry and adding to it.

Creating a Basic Subscriber Entry

Before you can create subscriber entries, the domain and the People organizational unit entries must exist. Once you have created those entries, you can edit a text file (for example, people.ldif) and enter the data for the subscriber. The basic subscriber entry has the single object class ispSubscriber, and very few mandatory attributes. The file for a basic subscriber looks like this:

dn: cn=Jane Doe (jldoe),ou=People,ou=wcgate1,ou=eng,o=sun,c=US 
commonname: Jane Doe (jldoe) 
sn: Doe
uid: jldoe 
userpassword: hidden 
objectclass: ispSubscriber

Where

dn

Is the distinguished name of the subscriber entry.

commonName

Is the naming attribute of a subscriber entry (ispSubscriber object class). For Solaris for ISPs subscribers and administrators, the value of the commonName attribute takes the form Firstname Lastname (userid).

sn

Is the surname of the subscriber.

uid

Is the login name of the subscriber.

userPassword

Is the password, limited to eight characters if you are sharing password information with UNIX accounts. This value is generated with the encryption method you set in the directory services administration console.

objectClass: ispSubscriber

Is the object class type of this subscriber entry.

You can create any number of subscriber entries by adding blocks of data with different attribute values to the file. When it is complete, save and close people.ldif. Obtain root access and add the subscriber entries to the directory with the following command, replacing the bind DN and password with your own:

# ldapadd -D "cn=admin,o=sun,c=US" -w password -f people.ldif

Adding FTP and Web Virtual Hosting Information

The information required for the specially-configured virtual hosting available with SunTM Internet FTP ServerTM and SunTM WebServerTM (SWS) adds only three attributes to the data file:

gidnumber: 60001 
uidnumber: 60001 
ispcontentdirectory: jldoe

Where

gidNumber

Is the UNIX group ID specified for this user in the virtually-hosted domain for FTP and Web services.

uidNumber

Is the UNIX user ID specified for this user in the virtually-hosted domain for FTP and Web services.

ispContentDirectory

Is the location (relative to the associated domain's document root) where this subscriber's content files are located.

Note -

Setting the values for the uidNumber and gidNumber attributes requires existing UNIX accounts properly set up to share access to the virtual FTP domain. See the Sun Internet FTP Server on-line help for information on defining a virtual host configuration.

You can create any number of subscriber entries by adding blocks of data to the file. When it is complete, save and close people.ldif. Obtain root access and add the subscriber entries to the directory with the following command, replacing the bind DN and password with your own:

# ldapadd -D "cn=admin,o=sun,c=US" -w password -f people.ldif

If you have already created these entries, you must perform an ldapmodify. Locate the manual page for ldapmodify(1) and follow those instructions.

Adding Remote User Information

An entry for a subscriber who gains access to ISP services through a RADIUS server must support an additional object class (remoteUser) and has several attributes added to the entry information.

Note -

The default Solaris for ISPs configuration designates the root domain as the search base for RADIUS subscriber entries. If your configuration is different, use the directory services administration console to configure RADIUS and enter values appropriate for your search base.

The additional lines in the ldif file are:

objectclass: remoteUser
authsuffixname: @ispxpress
grpcheckinfo: authSuffixName
grpcheckinfo: userPassword
authserviceprotocol: Framed-User
framedrouting: None
framedprotocol: PPP
grpreplyinfo: authServiceProtocol
grpreplyinfo: framedProtocol
grpreplyinfo: framedRouting

Where

objectClass: remoteUser

Is a required object class for the subscriber accessing services using a RADIUS server.

authsuffixname: @ispxpress

Is a suffix added to the subscriber's user name to enable the RADIUS server to distinguish among entries with the same uid in different domains. Enter the appropriate suffix for the specific user entry.

grpcheckinfo: authSuffixName

Indicates that the RADIUS server should verify the authSuffixName attribute value before selecting the entry to authenticate against.

grpcheckinfo: userPassword

Indicates that the RADIUS server should verify the userPassword attribute value before selecting the entry to authenticate against.

authserviceprotocol: Framed-User

If you are using the default RADIUS configuration, enter this attribute exactly as shown. The correct value is determined by the configuration of your network access server.

framedrouting: None

If you are using the default RADIUS configuration, enter this attribute exactly as shown. The correct value is determined by the configuration of your network access server.

framedprotocol: PPP

If you are using the default RADIUS configuration, enter this attribute exactly as shown. The correct value is determined by the configuration of your network access server.

grpreplyinfo: authServiceProtocol

Tells the RADIUS server to include the value of the authServiceProtocol attribute in its reply message.

grpreplyinfo: framedProtocol

Tells the RADIUS server to include the value of the framedProtocol attribute in its reply message.

grpreplyinfo: framedRouting

Tells the RADIUS server to include the value of the framedRouting attribute in its reply message.

You can create any number of subscriber entries by adding blocks of data to the file. When it is complete, save and close people.ldif. Obtain root access and add the subscriber entries to the directory with the following command, replacing the bind DN and password with your own:

# ldapadd -D "cn=admin,o=sun,c=US" -w password -f people.ldif

If you have already created these entries, you must perform an ldapmodify. Locate the manual page for ldapmodify(1) and follow those instructions.

The Complete ldif File

The complete ldif file for a complex user looks like:

dn: cn=Jane Doe (jldoe),ou=People,ou=wcgate1,ou=eng,o=sun,c=US 
commonname: Jane Doe (jldoe) 
sn: Doe
uid: jldoe 
userpassword: hidden 
gidnumber: 60001 
uidnumber: 60001 
objectclass: ispSubscriber 
objectclass: remoteUser
ispcontentdirectory: /home/users/jldoe
authsuffixname: @ispxpress
grpcheckinfo: authSuffixName
grpcheckinfo: userPassword
authserviceprotocol: Framed-User
framedrouting: None
framedprotocol: PPP
grpreplyinfo: authServiceProtocol
grpreplyinfo: framedProtocol
grpreplyinfo: framedRouting

Creating Group Entries

Before you can create group entries, a number of entries must already exist:

Once you have created those entries, you can start a text file (for example, groups.ldif) and enter the data for the group. A typical data set looks like the following:

dn: cn=isp-gp1,ou=Groups,ou=wcgate1,ou=eng,o=sun,c=US 
cn: isp-grp1
objectclass: groupOfNames
member: cn=Ed Anchor (anchor),ou=People,ou=wcgate1,ou=eng,o=sun,c=US
member: cn=April Shower (showers),ou=People,ou=wcgate1,ou=eng,o=sun,c=US
member: cn=Chili Jones (relleno),ou=People,ou=wcgate1,ou=eng,o=sun,c=US

Where

dn

Is the distinguished name of the group to be created.

cn

Is the relative distinguished name of the group entry.

objectClass

The object class groupOfNames distinguishes this type of entry.

member

Each member attribute takes as its value the distinguished name of an existing subscriber entry.

You can create any number of group entries by adding data to the file. When it is complete, save and close groups.ldif. Obtain root access and add the groups to the directory with the following command, replacing the bind DN and password with your own:

# ldapadd -D "cn=admin,o=sun,c=US" -w password -f groups.ldif

Solaris for ISPs Access Control

Solaris for ISPs sets access control for the directory services, to ensure proper access by parts of the software that require it while assuring security by preventing access by others. The general principal of these access controls is that all entities have read access while write access is restricted. It is very important that you do not change existing access controls, or you may introduce security risks or cause Solaris for ISPs to fail.

Remember that the access control rules are order sensitive. When Sun Directory Services checks for access, the first rule that applies to the request is used. Any remaining rules are ignored. Therefore, do not change the order of the rules in the file. When creating a new rule, be careful that it does not accidentally apply to existing Solaris for ISPs information and invalidate some access control rule already in place.

Note -

Access control checking is switched off if you bind to the directory as its administrator.

Generally, the information special to Solaris for ISPs is stored in entries supporting object classes defined in the Solaris for ISPs schema extension. Each of these classes is named beginning with the string "isp." Any rule in the access configuration file that contains such an object class (or attribute) is likely a Solaris for ISPs rule and, as such, sensitive to any changes. The access control rules are defined in /etc/opt/SUNWconn/ldap/current/dsserv.acl.conf.

For complete information on Sun Directory Services access controls, see Chapter 1, "Introduction to Directory Concepts," and Chapter 4, "Configuring a Directory Server," of the Sun Directory Services 3.1 Administration Guide.

The sections that follow describe the general behavior ensured by the Solaris for ISPs access controls. The phrase "has access" indicates that binding to the directory with that entry's DN and password will give the indicated form of access.

Rules Enabling Sun Internet Administrator Functionality

Sun Internet Administrator needs the following kinds of access to do its work:

Rules Enabling Service Functionality

The various Solaris for ISPs services need to record and access configuration information stored under their service entries (those located under the Services node in subdomains and virtual domains). Therefore, each has the access and information it need to write to create and modify entries in that portion of the DIT, including its own service entry.

Rules Enabling Proper User Access

Users (subscribers and administrators) have write access to their password attribute, but cannot change other parts of their entry. However, any administrator with management access to Sun Internet Administrator has global access and can change anything.