Solaris ISP Server 2.0 Administration Guide

Appendix A Configuring a Virtual Host

This appendix explains the steps you need to take to configure a virtual domain or virtual host in the Solaris ISP Server^TM directory service. Only the configuration steps for the directory service are covered; specific configurations for adding IP addresses or domain names and for ISP services such as FTP are not covered here.

The procedures in this appendix will assist you in creating a virtual domain that has its own set of subscribers who use a Sun Internet FTP Server virtual FTP site and a Sun^TM WebServer^TM virtual web site.

Topics include

Before You Begin

Before you configure the directory service to support a virtual host, you should plan for or implement the parts of the virtual host not related to the directory.

The first step in the configuration is registering a domain name and assigning an IP address. If you plan to use a Sun Internet FTP Servervirtual FTP site, you must assign a unique IP address to the virtual host to be used for FTP. If you do not require a virtual FTP site with domain-specific users, you may be able to use name based virtual hosting (where several domain names share the same IP address).

You must decide whether the virtual domain has subscribers and how they will use the system. The way that subscribers can log into the virtual host (or not) affects how you refer authentication requests in the directory and how you configure the location of virtual host data on disk.

Often a virtual host does not have unique subscribers (subscribers are authenticated in the domain of the hosting ISP or the subscribers do not actually store content at the ISP); in this case you may decide to ignore subscriber information or refer to a subscriber base (an ou=People node) that is not specific to the virtual host. In this case, you only need to plan the location of the virtual host data on disk and configure services accordingly.

Sometimes a virtual host requires only a single point of contact. An administrator from the customer's organization is the only person who actually logs in to store or remove data from a web site or FTP site. In this case, you may want to create a subscriber base unique to the virtual host, but in which the user's "home directory" is the root of the virtual web or FTP site rather than a personal directory.

Some virtual domains contain subscribers who are unique to that domain, who are not ISP subscribers, and who have personal web or FTP areas (for example, a small business that has its intranet hosted at your ISP). In this case, you will need to create a root directory for the FTP and web sites and a location for user personal directories. The virtual domain in the OSI tree will require an ou=People node with its own subscribers, and the hosts in the DC tree will point to this node to authenticate users. Each user entry will have an ispContentDirectory attribute naming the location of the personal directory for FTP and web site access.

Finally, if any subscriber will log in to the domain to store Sun Internet FTP Server data or Sun WebServer site content, you will need to create an ispService entry in the OSI tree that names the location of the content. The ispService object class ispDirectoryRoot attribute determines what part of the file system will be available to users when they authenticate in the virtual domain. If there are many subscribers with personal directories, you will want to designate a personal directory in each user's ispContentDirectory attribute.

Creating Directory Entries

The following procedures document how to create the entries in the directory to support a virtual host. The procedures show you how to create ldif files to use with ldapmodify to make the entries, but you may use the Deja tool instead. At the end of the section, there is an example ldif file with all of the entries you would make if you follow each procedure.

The examples in the procedures use the most complicated case: a virtual host with its own, unique set of subscribers who have personal directories for web and FTP content. The configuration you use may be less complicated, and may not require all of these procedures.

You only need to create these directory entries if you need to authenticate subscribers against the directory. If subscribers never authenticate with the FTP or web server (or any other service you may add that authenticates users against the directory), you do not need special entries in the directory.

The examples in the procedure will assume the following sample data:

There is a virtual domain called smallorg.com.
There is one virtual host in the domain, www.smallorg.com (111.112.113.14) , which subscribers use for web site content.
The site is also configured as a Sun Internet FTP Server virtual FTP site so that users may upload content using FTP.
The virtual domain is for an organization with multiple subscribers.
Subscribers are authenticated only in the virtual domain, not as subscribers to the main ISP organization.
The root directory of the virtual FTP site and web site is /var/hosts/smallorg/public/.
Each subscriber has a directory directly beneath the root directory (/var/hosts/smallorg/public/username/).
The name of the hosting ISP is "myISP," and it is represented in the OSI tree in the directory as the naming context o=myISP,c=US.

Entries in the DC Tree

The entries in the DC tree allow services to map the virtual host DNS name to an area in the OSI tree where service configuration and subscriber data is stored.

By default, the DC tree contains a top level dc=com node representing the .com top-level DNS domain. Each host is represented by a chain of dc nodes that are children of the top node. For example, www.sun.com would be represented as dc=www,dc=sun,dc=com.

If you need to add hosts that are not in the .com domain, you will need to create another naming context (for example, a top-level dc=net node). See "Adding More Top-level Domains" for more help with creating a new naming context.

To Create the Domain in the DC Tree

Determine the name of each virtual host subscribers may authenticate on.

You only need to configure the hosts that will use the directory to authenticate users.

In this example, we will use one host: www.smallorg.com

If there is no naming context for the top-level domain for the virtual host, create one.

You can view the current naming contexts using Deja or by using the web gateway (if it is enabled) .

If there is no dc=com domain, for example, you will need to create one before www.smallorg.com can be added. See "Adding More Top-level Domains" for more help with creating a new naming context.

Determine the distinguished name (dn) of the node in the OSI that contains the subscribers who use this host. This will be the associatedName attribute on the dc entry for the host.

This example assumes that the domain smallorg.com has its own unique set of subscribers. The entries may not exist in the directory yet, but they will be created later. The dn in the OSI tree will be ou=SmallOrg,o=myISP,c=US.

Create a text file for the ldif entries.

For example, /tmp/smallorg.ldif.

For each dc node you need to add, create an ldif entry naming the dn (dc=name), the objectclass (domain), dc, and the associatedName in the OSI tree.

For our example, we need to add dc nodes for smallorg (beneath com) and www (beneath smallorg). The dc=www node needs to point to the proper place in the OSI tree so that the correct users can log in to that host.
```
dn: dc=smallorg,dc=com
dc: smallorg
objectclass: domain

dn: dc=www,dc=smallorg,dc=com
dc: www
objectclass: domain
associatedname: ou=SmallOrg,o=myISP,c=US
```

Save the file.

You may run ldapadd now to add the entries, or continue with the other procedures and add all of the required ldif entries to the file first.

To run ldapadd on the host where the Solaris ISP Server directory server is running:
% cd /opt/SUNWconn/bin % ./ldapadd -D cn=admin,o=myISP,c=US -w secret -f /tmp/smallorg.ldif

Continue with the procedure in "Entries in the OSI Tree".

Entries in the OSI Tree

The OSI tree must contain entries for the subscribers who will be authenticated on the virtual host.

The virtual host or virtual domain does not need to have its own set of subscribers; the virtual host services can authenticate users against the general ISP subscriber base. If you wish to have users authenticated against the general ISP subscriber base, make the associatedName attribute on the dc entries in the DC tree point to the top DN in the OSI tree (for example, ou=myIsp,c=US).

If you create a new domain in the OSI tree, you need to create an organizationalUnit (ou) node naming the domain with an associatedDomain attribute that points to the proper domain or host name in the DC tree. Below the virtual domain ou, you need to create ou nodes for People (to contain ispSubscriber entries), Groups, and Services (to contain ispService entries). Populating the People and Services portions of the tree is explained in "Entries for Users for the Domain" and "Entries for Services in the Domain" below.

The procedure below uses a virtual host with its own set of subscribers. Since these subscribers are unique to the virtual domain, we need to create an ou node in the OSI tree for the domain and set its associatedDomain attribute to the name of the virtual domain in the DC tree.

To Create the Domain in the OSI Tree

Determine the distinguished name for the domain in the OSI tree. The distinguished name includes the ou node for the domain, and all of the parents of that node in the tree.

In this procedure we will create a domain directly below a top distinguished name of o=myISP,c=US. The dn of the domain is ou=SmallOrg,o=MyISP,c=US.

Since we have only one host in the example, we could be more specific and use ou=www,ou=SmallOrg,o=MyISP,c=US. By only specifying the domain, it is possible to add more virtual hosts to the domain later that use the same subscribers (for example, if mail.smallorg.com is created later).

Determine the dn of the virtual host in the DC tree. This will be used in the associatedDomain attribute.

For example, dc=smallorg,dc=com.

Create a text file for the ldif entries.

For example, /tmp/smallorg.ldif.

Create an ldif entry for the domain specifying the dn, its object class attributes, the ou, and the associatedDomain.

The object classes are always organizationalUnit and domainRelatedObject.

For this example, dn=ou=SmallOrg,o=MyISP,c=US and the associatedDomain is smallorg.com (note that the associatedDomain is specified as a domain name and not as a distinguished name).

Here is what would be entered into the ldif file:
```
dn: ou=SmallOrg,o=MyISP,c=US
ou: SmallOrg
associatedDomain: smallorg.com
objectClass: organizationalUnit
objectClass: domainRelatedObject
objectClass: top
```

Create ldif entries for the People, Groups, and Services nodes in the domain.

These nodes all have organizationalUnit object classes, and are used to contain other data for the virtual domain.

The following would be added to the end of the example ldif file:

dn: ou=People,ou=SmallOrg,o=MyISP,c=US
ou: People
objectClass: organizationalUnit

dn: ou=Groups,ou=SmallOrg,o=MyISP,c=US
ou: Groups
objectClass: organizationalUnit

dn: ou=Services,ou=SmallOrg,o=MyISP,c=US
ou: Services
objectClass: organizationalUnit

Save the file.

You may run ldapadd now to add the entries, or continue with the other procedures and add all of the required ldif entries to the file first.

To run ldapadd on the host where the Solaris ISP Server directory server is running:
% cd /opt/SUNWconn/bin % ./ldapadd -D cn=admin,o=myISP,c=US -w secret -f /tmp/smallorg.ldif

Entries for Users for the Domain

After you create the domain in the OSI tree, you can add entries for the users of that domain below the ou=People node. For detailed information on creating users, see Chapter 5, Making Subscriber Directory Entries.

The ispSubscriber attributes specific to the virtual host are ispContentDirectory and ispAuthorizedServices.

ispContentDirectory specifies the user's directory on the virtual host. The directory is relative to the value of the ispDirectoryRoot of the service the user accesses (see "Entries for Services in the Domain" for information on this attribute). The ispContentDirectory is used by the Sun Internet FTP Server and the Sun WebServer to determine where to store content that a user puts on the virtual host.

If a virtual host only has one authorized user (an administrative account for a hosted web site, for example), you may wish to create a single subscriber in the domain who only has access to the web site directory. In this case, the ispContentDirectory could be "/" to indicate that when the user logs in to the Sun Internet FTP Server his or her root directory will be the ispDirectoryRoot of the FTP site.

ispAuthorizedServices specifies the distinguished names of services in the virtual domain that the user can access (if authentication is required). An example dn value for this attribute is ispVersion=2.1,ou=SUNWhttp,ou=Services,ou=SmallOrg,o=MyISP,c=US.

The following example shows an ldif entry for a subscriber that could be part of the www.smallorg.com domain described in other sections:

dn: cn=John Doe (jdoe),ou=People,ou=SmallOrg,o=MyISP,c=US
objectClass: top
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: ispSubscriber
cn: John Doe
sn: Doe
givenName: John
userId: jdoe
userPassword: secret
uidNumber: 19995
gidNumber: 101
ispContentDirectory: jdoe/public_html
ispauthorizedServices: ispVersion=1.0,ou=SUNWftp,ou=Services,ou=SmallOrg,o=MyISP,c=US
mail: jdoe@myisp.com

Entries for Services in the Domain

Each service that the users in the virtual domain can log in to requires an ispService entry beneath the ou=Services node in the domain. The only service bundled with the Solaris ISP Server software that can authenticate users in virtual domains is Sun Internet FTP Server, so that is the only service covered in this section.

The Sun WebServer uses the ispDirectoryRoot of a Sun Internet FTP Server entry to determine where to store or find user personal content. If users have personal web site directories, create an ispService entry for a Sun Internet FTP Server service even if a virtual FTP site has not been created.

To Create a Sun Internet FTP Server Service Entry

Determine the directory root used by the Sun Internet FTP Server or Sun WebServer service on the virtual host.

This example will use /var/hosts/smallorg/public/. Beneath this directory there may be a ./pub directory for anonymous FTP, web site content, and user directories in ./username/public_html.

Create a text file for the ldif entries.

For example, /tmp/smallorg.ldif.

Add an ou entry for SUNWftp to the Services node for the domain.

dn: ou=SUNWftp,ou=Services,ou=SmallOrg,o=MyISP,c=US
ou: SUNWftp
objectClass: organizationalUnit

Add an ispService entry beneath the SUNWftp entry. The dn of this entry is the ispVersion attribute plus the dn of the SUNWftp entry you just added.

The ispVersion attribute is always "1.0."
```
dn: ispVersion=1.0,ou=SUNWftp,ou=Services,ou=SmallOrg,o=MyISP,c=US
ispVersion: 1.0
cn: SUNWftp
objectClass: ispService
ispDirectoryRoot: /var/hosts/smallorg/public
```

Save the file.

Run ldapadd now to add the entries.

To run ldapadd on the host where the Solaris ISP Server directory server is running:
% cd /opt/SUNWconn/bin % ./ldapadd -D cn=admin,o=myISP,c=US -w secret -f /tmp/smallorg.ldif

Example ldif File

For reference, the listing below shows the complete contents of an ldif file with all of the example entries used in this Appendix:

Example A-1 Complete ldif File to Add a Virtual Host

dn: dc=smallorg,dc=com
dc: smallorg
objectClass: domain

dn: dc=www,dc=smallorg,dc=com
dc: www
objectClass: domain
associatedName: ou=SmallOrg,o=myISP,c=US

dn: ou=SmallOrg,o=MyISP,c=US
ou: SmallOrg
associatedDomain: smallorg.com
objectClass: organizationalUnit
objectClass: domainRelatedObject
objectClass: top

dn: ou=People,ou=SmallOrg,o=MyISP,c=US
ou: People
objectClass: organizationalUnit

dn: ou=Groups,ou=SmallOrg,o=MyISP,c=US
ou: Groups
objectClass: organizationalUnit

dn: ou=Services,ou=SmallOrg,o=MyISP,c=US
ou: Services
objectClass: organizationalUnit
dn: cn=John Doe (jdoe),ou=People,ou=SmallOrg,o=MyISP,c=US
objectClass: top
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: ispSubscriber
cn: John Doe
sn: Doe
givenName: John
userId: jdoe
userPassword: secret
uidNumber: 19995
gidNumber: 101
ispContentDirectory: jdoe/public_html
ispauthorizedServices: ispVersion=1.0,ou=SUNWftp,ou=Services,ou=SmallOrg,o=MyISP,c=US
mail: jdoe@myisp.com

dn: ou=SUNWftp,ou=Services,ou=SmallOrg,o=MyISP,c=US
ou: SUNWftp
objectClass: organizationalUnit

dn: ispVersion=1.0,ou=SUNWftp,ou=Services,ou=SmallOrg,o=MyISP,c=US
ispVersion: 1.0
cn: SUNWftp
objectClass: ispService
ispDirectoryRoot: /var/hosts/smallorg/public

Adding More Top-level Domains

The DC tree is configured with dc=com as the naming context, making .com the (only) top-level domain. You may need to add other naming contexts to support virtual hosts that are not in the .com domain.

The following procedure documents how to use the Sun Directory Services dsadmintool administration console to create an additional DC tree for the .net domain. The same procedure, of course, applies to any top-level domain.

The Sun Directory Services software supports up to four naming contexts in a data store, or three DC tree naming contexts and the OSI tree. If your ISP requires more than three top-level domain naming contexts, see the procedure "To Create an Additional Data Store" below.

To Add a DC Tree for Another Domain

Run /opt/SUNWconn/sbin/dsadmintool.

dsadmintool is an X application. Make sure your DISPLAY environment variable is properly set if you are not at the console.

Click Data Store in the Sections list to display the Data Store section.

Click the Datastore folder in the Data Store section to select it.

Choose Modify Data Store from the Selected menu.

The Modify Data Store dialog is displayed.

Click the More Suffixes button.

A new Additional Suffix text field displays at the end of the list.

Type "dc=" and the name of the top-level domain you want into the Additional Suffix field.

For example, to add a DC tree for the .net domain, enter dc=net.

Click OK to apply the change and close the Modify Data Store dialog.

In the Sun Directory Services administration console window, click Apply to save the changes to the Data Store and restart the server.

A dialog will prompt you to ask if you want to restart the server. The new naming context will not be available until the server has been restarted. The remaining steps assume that you have restarted the server so that an entry can be added to the new naming context.

Create an ldif file with a domain entry for the root of the new naming context.

For example:
```
dn: dc=net
objectClass: domain
objectClass: top
dc: net
```

Run ldapadd to add the entry to the directory.

For example:

% cd /opt/SUNWconn/bin
% ./ldapadd -D cn=admin,o=MyISP,c=US -w secret -f /tmp/net.ldif

To Create an Additional Data Store

Use this procedure if you require more than three top-level domains. This procedure shows you how to create an additional data store so that you can have more than four naming contexts. The new data store is created in the same database directory as the original store, but you are not required to keep them in the same location.

Additional data stores will use a different rootdn entity. When you bind to the directory you will need to bind as the rootdn appropriate to the data store. To avoid this and have a single identity that can be used to bind and make changes in any data store, create a record in the directory representing an administrative user and give that user permission to make changes in any data store. The next procedure, "To Create a Directory Administrator" explains how to create this user and configure permissions.

Refer to Sun Directory Services 3.1 Administration Guide for complete details on creating data stores.

Run /opt/SUNWconn/sbin/dsadmintool.

dsadmintool is an X application. Make sure your DISPLAY environment variable is properly set if you are not at the console.

Click Data Store in the Create menu to display the Create Data Store dialog.

Enter a suffix for at least one naming context in this data store in the Datastore Suffix field.

For example, dc=uk.

If you want to add more that one suffix, click the More Suffixes button.

Enter a path where the data will be stored in the DB Directory field.

The original data store is located in /var/opt/SUNWconn/ldap/dbm by default. You may also want to store additional data stores in /var/opt/SUNWconn/ldap.

You may want to change some of the other settings.

The following are the default settings for the original Solaris ISP Server data store:

Read-only Datastore

off

Last-modification attributes

on

Cache size (entries)

5000

Cache size (bytes)

100000

Congestion Limits: critical

200

Congestion Limits: congested

500

Congestion Limits: back to normal

1000

Click OK to save your changes and create the data store.

The data store should now appear in the Data Store list in the dsadmintool Properties page.

Click Apply in the dsadmintool console window to apply your changes to the configuration.

Stop and restart the LDAP service using dsadmintool or /etc/init.d/dsserv.

Now add a record representing the root node in the naming context of the new data store.

The following example ldif record could be used with ldapadd to create a record for dc=uk:
```
dn: dc=uk
objectClass: domain
objectClass: top
dc: uk
```
To add this record to the new data store, you will have to bind as the rootdn of the new data store. The new rootdn uses the original rootdn common name, but with the new naming context. For example, if the cn of the original rootdn is admin, then to add the above record to our new data store with the dc=uk naming context:
# cd /opt/SUNWconn/bin # ./ldapadd -D cn=admin,dc=uk -w secret -f /tmp/net.ldif
You should create a single administrator record that can be used to bind to all of your data stores to avoid having to bind with different credentials to each data store. See the next procedure, "To Create a Directory Administrator" for more information.

Note -
Even if you create an administrative user entry, the first record in any new data store must be created by the rootdn defined for that data store. So you must add the root record for the data store's naming context by binding as the data store rootdn. Subsequent records may be added by any dn with appropriate write privileges.

To Create a Directory Administrator

This procedure explains how to create a record representing an administrator that can bind to any data store an make modifications. You will create a record in the original data store, then add permissions to the access control list (ACL) file to grant this user permission to modify all entries.

This procedure uses an example of creating a record with the distinguished name "cn=admin,o=myISP,c=US" and a password of "secret." Note that the common name and distinguished name you choose can be identical to the common name and distinguished name of the actual rootdn in your data store.

Create an entry in one of your naming contexts for the user that will act as the administrator.

You should place the entry in your original OSI tree; for example, a user whose distinguished name is cn=admin,o=myISP,c=US.

The object class can be any object class that accommodates a password attribute. Using the top and person object classes is sufficient, but you may want to use other object classes (such as organizationalPerson) if you want to store more information in the record's attributes.

The following ldif file is sufficient to create an administrative user:
```
dn: cn=admin,o=myISP,c=US
objectClass: top
objectClass: person
cn: admin
sn: admin
userpassword: secret
description: rootdn record
```
You can create the record using ldapadd or the Deja tool.

Edit the access control lists (ACLs) for the directory service using either dsadmintool or by editing the dsserv.acl.conf file.

The configuration file is located in /etc/opt/SUNWconn/ldap/current by default.

Add an ACL to allow only the administrative user to modify its own record.

For entries that match the dn of the administrative user that you just created, allow "self" write access and everyone (*) no access.

In the dsserv.acl.conf file, the following entry would allow only the user we created above to modify its own record:
```
access to dn="cn=admin,o=myISP,c=us" 
     by self write
     by * none
```
The ACLs are applied in the order in which they appear in the file, so make this the first entry in the file.

Add an ACL that allows the administrative user to modify all records in all naming contexts.

This ACL should use a dn pattern to match any distinguished name and explicitly allow write access to the administrative user. Use ".*=.*" as the dn pattern to match any dn. Be sure to place this entry at or near the top of the ACLs list so that it is matched before any other entries that might block access.

In the dsserv.acl.conf file, the following entry would grant the user we created above permission to modify any record:
```
access to dn=".*=.*" 
     by dn="cn=admin,o=myISP,c=us" write
```

Stop and restart the LDAP service using dsadmintool or /etc/init.d/dsserv.