htrealm(1M)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | EXIT STATUS | ATTRIBUTES | FILES | SEE ALSO | NOTES

NAME

/usr/bin/htrealm- Manages realms, users, and groups used to configure access control lists (ACLs) on a Sun^TM WebServer^TM web site.

SYNOPSIS

htrealm add [-h hostname-i instance] [-p] -r realmname {[-u userid[-A]]| [-s [HTPASSWD]| [ISP]| [ISPADMIN]| [ UNIXSYS][-d data_dir]]| [-g groupname[-m individuals]]} [-v] -z admin_name
htrealm delete [-h hostname-i instance] [-p] -r realmname [[-u userid[-A]]| [-g groupname[[-A]| [-m individuals]]]] [-v] -z admin_name
htrealm help [[add]| [delete]| [list]]
htrealm list [-h hostname-i instance] [-r realmname{[-A]| [-u [ userid]]| [-g [ groupname]]}] [-p] [-v] -z admin_name
htrealm version

DESCRIPTION

Realms in Sun WebServer define sets of protection spaces or authentication domains consisting of user names, groups, and passwords. Sun WebServer uses realm information to determine how a user is authenticated. For example, a UNIX-based realm stores user and password information as well as group information in appropriate files or tables if distributed NIS/NIS+ is used. For HTPASSWD realms, you can define your own set of users and groups in a realm. Regardless of how the realm information is stored and accessed, the access control settings require realms to protect resources.

Realms are also differentiated based on how they are used. Two different realms can have different names with the same underlying users and groups database. This gives additional flexibility in naming the authentication domains displayed in the browser.

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 GUI 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 member.

delete

Deletes a given realm, user, group, or member.

help

Displays help on usage.

list

Lists all realms, users, groups, or members.

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 realm. 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 are running on the Solaris ISP Server software, -d can also be used when -s is ISPADMIN to specify the ISP Component ID and version. The default is site_path/conf/realms/realmname when used with an HTPASSWD realm, and "SUNWhttp-2.1" when used with an ISPADMIN realm. 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 (HTPASSWD, ISP, ISPADMIN, or UNIXSYS). 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 ISP Server 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 ISP Server Sun^TM Internet Administrator^TM. The -d flag takes the ISP-component ID and version (for example, "SUNWftp-2.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

Configures a web site's ACLs.

/etc/http/access.conf

Configures the server administration ACLs.

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
}

SEE ALSO

realms.conf(4), htaccess(1m), access.conf(4), htpasswd(1m)

NOTES

If the command is run by root user, then the user name 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.1  Last Revised 22 February 1999

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | EXIT STATUS | ATTRIBUTES | FILES | SEE ALSO | NOTES