htrealm(1M) (Sun WebServer Command Reference)

Sun WebServer Command Reference

htrealm(1M)

NAME

^TM

SYNOPSIS

htrealm

-A

-d

data_dir

-g

groupname

-h

hostname

-i

instance

-m

individuals

-p

-r

realmname

-s

-u

userid

-v

-z

admin_name

htrealm

-A

-m

individuals

-g

groupname

-h

hostname

-i

instance

-p

-r

realmname

-u

userid

-v

-z

admin_name

htrealm

-A

-u

userid

-g

groupname

-r

realmname

-h

hostname

-i

instance

-p

-v

-z

admin_name

htrealm

DESCRIPTION

Realms in Sun WebServer define sets of protection spaces or authentication domains consisting of user names, groups, and passwords. Access controls based on password authentication use a realm to determine how to authenticate users. For example, a person may have a user name and password for a UNIX® system account and a different set of credentials for Sun WebServer administration. The realm used to protect a resource on a web site would determine which password the person would need.

Realms are also differentiated based on how they are used. You can define two realms, for example, that both use UNIX user names and passwords. One realm could be named "admins" and another "subscribers." Both use the same set of valid UNIX system users, but in practice you might only use "admins" with access control lists (ACLs) that are restricted to a small set of users. When prompted to enter a password for the "admins" realm or the "subscribers" realm, the user knows which password to enter and whether the user has access to the data (that is, the user knows the purpose for authenticating). If "admins" and "subscribers" were HTPASSWD realms, they will have different ACLS and user names.

Most browsers display the realm name in the prompt when a user name and password are required, so the realm name should indicate to users the purpose for password protection and which user name and password to use.

The htrealm command can be used to create, delete, and list realm definitions for use with ACLs. It can also be used to manage users and groups in HTPASSWD realms. HTPASSWD realms are Sun WebServer specific in that their data is stored in user and group files with Sun WebServer configuration.

Realms in the global /etc/http/ directory are independent of any web site. These realm definitions are used only for server administration; the user names and passwords are used to log into the Sun WebServer Administration Console or to execute commands such as htserver. Only one such realm may be in use at any given time. The server administration realm must be defined in /etc/http/realms.conf and used to protect the /sws-administration URI in /etc/http/access.conf.

OPTIONS

Subcommands

The following subcommands are supported:

add: Adds a given realm, user, group, or memeber.
delete: Deletes a given realm, user, group, or member.
help: Displays help on usage.
list: Lists all realms, users, groups, or memebers.
version: Displays the version of htrealm.

Options

The following options are supported:

-A

Indicates that the user or group specified with the -u or -g flags has administrative privileges of the ACL. The administrators must already be valid principals within the realm. Valid with all subcommands (but used most frequently to add, delete, or list realm administrators).

-d data_dir

Specifies a directory relative to the site path where the users and groups files for an HTPASSWD realm are stored. data_dir is required and valid only if -s is HTPASSWD, or if you're running on Solaris for ISPs, ISPADMIN. The default is site_path/conf/realms/realmname. Valid with the add subcommand.

-g groupname

Specifies a set of users with permission to access the resources in the realm. Separate multiple group names with white space. Valid with all subcommands.

-h hostname

Specifies the name of the virtual host containing the realm. Valid with all subcommands.

-i instance

Specifies the name of the server instance. Valid with all subcommands.

-m individuals

Specifies the individual members of the group. This is a comma-separated list. Valid with the add and delete subcommands.

-p

Turns off the prompting for the password such that passwords are taken in from stdin and scripts may pipe (|) passwords. Valid with all subcommands.

-r realmname

Specifies the realm name. White spaces must be inside double quotes. Valid with all subcommands.

-s source_name

Specifies the source of the realm (UNIXSYS or HTPASSWD). Valid with the add subcommand.

HTPASSWD: Indicates that the user or group information is retrieved using the Sun WebServer users/group file format, and that user and group information will be maintained in the data directory named by realm_dir. The htrealm(1m) utility is used to create, delete, and list users and groups and modify passwords using htpasswd.
ISP: Indicates that the realm information is stored in the Solaris^TM for ISPs shared directory service. Changes to user and group information cannot be made through Sun WebServer.
ISPADMIN: Indicates that the principals are Administrators in the Solaris^TM for ISPs^TM Management Console. The -d flag takes the ISP-component ID and version (for example, "SUNWfinger-1.0").
UNIXSYS: Indicates that the operating system user and group definitions will be used to authenticate users in the realm. Changes to user and group information cannot be made through Sun WebServer.

-u userid

Specifies the realm user with permission to modify realm data. Separate multiple user names with white space. Valid with all subcommands.

-v

Displays verbose status messages. Valid with all subcommands.

-z admin_name

Specifies the name of the realm administrator. Valid with all subcommands.

EXAMPLES

Example 1

To create a site-specific realm called Subscribers on the web site www.A.com, you create at least one user and one realm administrator:

# htrealm add -i sws_server -h www.A.com -r Subscribers \\ 
  -s HTPASSWD

# htrealm add -i sws_server -h www.A.com -r Subscribers \\ 
  -u user1
Setting password for the user user1.
Password:
Confirm Password:

# htrealm add -i sws_server -h www.A.com -r Subscribers \\ 
  -u user1 -A

Example 2

A nonroot user can add a realm if a valid user name and password from the serverAdmin realm are supplied:

% htrealm add -i sws_server -h www.A.com -r System \\ 
  -s UNIXSYS -z admin
Enter Password for admin:

% htrealm list -i sws_server -h www.A.com -z admin
Enter Password for admin:
siteAdmin       HTPASSWD        -
System          UNIXSYS         -

EXIT STATUS

The following exit values are returned:

0: Successful completion.
>0: An error occurred.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWhttp
Interface Stability	Evolving

FILES

The following files are used by the command-line utilities:

site_path/conf/access.conf

A web site's ACLs configuration file.

/etc/http/access.conf

The server administration ACLs configuration file.

site_path/conf/access.conf

A web site's ACLs configuration file.

/etc/http/access.conf

Defines the realms used to define users for server administration.

site_path/conf/realms.conf

Defines realms of user and group information used by access control lists on a Sun WebServer web site.

site_path/conf/realms/HTPASSWD_realm_name/users

Lists the users in the HTPASSWD realm.

Entries in this file have the form username:password.

site_path/conf/realms/HTPASSWD_realm_name/groups

Lists the groups in the HTPASSWD realm.

Entries in this file have the following form:

group <group_name> {
	member1
	member2
	member3
}

NOTES

If the command is run by root user, then the username and password of an administrator are not required.

Users other than root must use the -z option and pass the user name and password of a valid administrator to the command.

Sun WebServer 2.0 Last Revised 17 July 1998

htrealm(1M)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLES

Example 1

Example 2

EXIT STATUS

ATTRIBUTES

FILES

SEE ALSO

NOTES