|
| Sun ONE Application Server 7 Administrator's Guide |
Configuring Administrative DomainsThis module explains how to set up and administer administrative domains with your Sun ONE Application Server.
This module includes the following topics:
About Administrative Domains
Administrative domains provide a basic security structure whereby different administrators can administer specific groups (domains) of application server instances on a machine. By dividing the application server instances up like this it is possible to share a single machine between disparate organizations, each with their own administrator.
Within the Sun One Application Server every application server instance is a member of one domain. It is not required that there be any more than one domain, however, multiple domains are supported as a useful feature if so desired.
Administrative security is established for local commands using the underlying operating system's security mechanisms (that is, via file permissions). Remote command security is established using a username/password pair to communicate with a specific admin server. Administrative domains don't utilize any other security constructs.
This section describes the following topics:
Implementing Administrative Domains
A domain is implemented using files, operating system processes and ports. Each domain has a unique name.
Directory Structure
There are files (configuration, executables, and so on) that are shared by all domains within an installation. What is important for this discussion are those files which are specific to a domain.
The files specific to a domain all share a common root directory known as the domain directory, and whose name is the name of the domain. Under the domain directory is one directory per instance, each named after the instance, and under each of those instance directories are instance-specific files.
A domain directory can be constructed anywhere in the file system (in accordance with security permissions and other operating system level constraints). Unless a user chooses otherwise, domain directories are constructed under a default directory (known as the domains directory). However a user can choose to create a domain directory anywhere.
Process/Port Structure
When a domain is running it consumes operating system processes and ports. Specifically, for each instance running within a domain (including the domain's admin server) there is a process and a port.
Configuring Domains
Domains can be created, deleted, listed, started and stopped using commands specifically designed for that purpose.
Creation, deletion and starting of domains can only be done locally, whereas listing and stopping can be done both locally and remotely.
The deletion, starting and stopping commands all take a domain name. This name is optional if there is only one domain. The command will give an error if no domain was given but there are multiple domains configured.
This section contains the following topics:
Creating Domains
Domains are created using the create-domain command. This command is local only.
Synopsis:
asadmin create-domain [--path domain_path] [--sysuser sys_user] [--passwordfile file_name] --adminport port_number --adminuser admin_user --adminpassword password domain_name
Example: creating a domain in the default location
$ asadmin create-domain --adminport 123 --adminuser MyAdmin --adminpasswd MyPassword MyDomain
This example creates a domain called MyDomain in the default location (that is, the domains directory). The administration server will listen on port 123, the admin user name will be MyAdmin and the password will be MyPassword. The domain directory and files underneath it will be owned by the operating system user who executed this command. In addition, the operating system processes will run as the user who executed this command.
If there's already a domain called MyDomain then an error message is returned.
(Note that instead of using the password on the command line, which could be a security issue, you can put the password in a file and pass it through in using the --passwordfile option).
Example: creating a domain somewhere other than the default location
$ asadmin create-domain --path $HOME --adminport 123 --adminuser MyAdmin --adminpasswd MyPassword MyDomain
This example is similar to the first, except that the domain directory will now be located underneath the user's $HOME directory rather than under the default domains directory.
Example: creating a domain for another user (UNIX only)
# asadmin create-domain --user AnotherUser --adminport 123 --adminuser MyAdmin --adminpasswd MyPassword MyDomain
This example is similar to the first, except that the domain and its files will be owned by the user AnotherUser, as will the operating system processes
Using the --user option provides the ability for one user to construct domains that other users can subsequently administer. This option requires that the user running the create-domain command be root.
User Permissions on UNIX Platforms
In order for a non-root user to create and delete administrative domains, you must add the user ID to a UNIX group that has write permissions to the domain configuration files:
- Create a UNIX group that will be the group which is applied to the installation-wide domain configuration files. For example, a UNIX group named asadmin.
- Set the installation-wide domain configuration files located under /etc/appserver to be owned by the newly created UNIX group.
The files are named domains.bin and domains.lck. For example, after changing the group assigned to these files:
-rw-r--r-- 1 root asadmin 0 Sep 18 14:34 domains.bin
-rw-r--r-- 1 root asadmin 0 Sep 18 14:34 domains.lck
- Enable write access to these files by the newly created UNIX group. In this example, the resulting permissions would look like the following:
-rw-rw-r-- 1 root asadmin 0 Sep 18 14:34 domains.bin
-rw-rw-r-- 1 root asadmin 0 Sep 18 14:34 domains.lck
- Add the user ID to the UNIX group.
Alternatively, if you do not want to provide non-root users with write access to the installation-wide configuration files, you can create an administrative domain on behalf of a user. During creation of a new administrative domain, specify the --sysuser and --path options to identify the UNIX user ID that will own the domain's directories and files and the location under which the administrative domain will be created. For an example, see "Example: creating a domain for another user (UNIX only)".
Once an administrative domain is created under a user ID, the user may create new application server instances and perform a wide variety of administrative operations on the application server instances. The user ID does not need to belong to the UNIX group that has write privileges for the administrative domain configuration file. Membership in the UNIX group is required only to create and delete administrative domains.
Deleting Domains
Domains are deleted using the delete-domain command. Only the operating system user (or root) who can administer the domain can execute this command successfully. This command is local only.
Synopsis:
asadmin delete-domain [domain_name]
Example: deleting a domain
$ asadmin delete-domain MyDomain
This example deletes the domain called MyDomain on the local machine.
Listing Domains
The domains created on a machine can be found using the list-domains command.
This command can operate both locally and remotely.
Synopsis:
asadmin list-domains [--host host] [--port port] [--password password] [--user user]
Example: listing the domains on a local machine
$ asadmin list-domains
domain1 [/opt/ias/build/domains/domain1]
Example: listing the domains on the local machine using the remote option:
$ asadmin list-domains --user admin --password password --host localhost --port 4848
domain1 [/opt/ias/build/domains/domain1]
Starting Domains
Domains can be started using the start-domain command. This starts up the domain's admin server and all other instances in the domain.
This command can only be run locally.
Synopsis:
asadmin start-domain [--domain domain_name]
Example: starting the only domain on a machine:
$ start-domain
Instance domain1:admin-server started
Instance domain1:server1 started
Domain domain1 Started.
Stopping Domains
Domains can be stopped using the stop-domain command. The user can choose to stop every instance within a domain, or all the instances except the admin server, thus leaving the domain able to be remotely administered.
This command can be run both locally and remotely.
Synopsis:
asadmin stop-domain [--user admin_user] [--password admin_password] [--host host_name] [--port port_name] [-- local=false] [--domain domain_name] [--adminserv=true] [--passwordfile file_name] [--secure | -s]
Example: Stopping all instances in a domain except for the admin server instance.
$ asadmin asadmin stop-domain --user admin --password password --host localhost --port 4848 --adminserv=false --domain domain1
DomainStoppedRemotely
Recreating the Domain Registry
For implementation purposes the details of each domain (its name, location, ports used, and so on) are recorded in a file known as the domain registry.
Under normal operating conditions you should not have to do anything with the domain registry directly, since any modification or use of the domain registry is entirely encapsulated by the commands used to administer the system. However, because the domain registry is a file, it can become corrupted (for example, when a script goes wrong, or when someone inadvertently deletes the registry, and so on), and in those cases you may have to recreate the file.
Note You can access the domain registry through the command line interface by using the asadmin command.
If the registry becomes corrupted, perform the following procedure to recreate the registry:
- Get a list of all the domains, and the directory (default or non-default) that they're located in.
- Rename each directory (for example, append each directory name with the suffix ".bak")
- Create each domain again in its original location, using default values for ports, passwords, and so on.
- Delete each new domain directory and replace it with the original directory.
- For each domain execute the reconfig command. This will cause the domain registry to be updated with the values from the old domain.