path: root/usr/src/man/man1m/smtnrhdb.1m

'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SMTNRHDB 1M "Dec 19, 2008"
.SH NAME
smtnrhdb \- manage entries in the tnrhdb database
.SH SYNOPSIS
.LP
.nf
\fB/usr/sadm/bin/smtnrhdb\fR \fIsubcommand\fR [\fIauth_args\fR] \fB--\fR \fIsubcommand_args\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsmtnrhdb\fR command adds, modifies, deletes, and lists entries in the
\fBtnrhdb\fR database.
.sp
.LP
The \fBtnrhdb\fR database specifies which remote-host template to use for each
host, including the local host, in the distributed system. If a host's  IP
address cannot be matched to some entry in the \fBtnrhdb\fR database,
communication with the host is not permitted.
.sp
.LP
The \fBsmtnrhdb\fR command requires the Solaris Management Console to be
initialized for the command to succeed (see \fBsmc\fR(1M)). After rebooting the
Solaris Management Console server, the first \fBsmc\fR connection can time out,
so you might need to retry the command.
.SS "Valid Host Addresses and Wildcards"
.sp
.LP
The trusted network software uses a network "longest prefix of matching bits"
mechanism when looking for a host. The software looks first for the IP address
of the host. If the software does not find this address, then the software
falls back to searching for an IP address with the longest prefix of a matching
bit pattern, and so on.
.LP
Note -
.sp
.RS 2
The actual numeric value of the subnet  address or other subnetting
information on the system (for example, from the \fBnetmasks\fR(4)  file)  are
not considered by this mechanism.
.RE
.sp
.LP
Using the "longest prefix of matching bits" mechanism, an IPv4 address of
0.0.0.0 is a wildcard address with a prefix length of 0 and hence matches any
IPv4 address. For more information about prefi x lengths in IPv4 and IPv6
addresses, see \fISystem Administration Guide: IP Services\fR.
.sp
.LP
The \fBsmtnrhdb\fR command accepts a hostname, IP address, and wildcard address
with as optional prefix as valid addresses. See \fIsubcommand_args\fR, below,
for the format of valid addresses.
.SH SUB-COMMANDS
.sp
.LP
\fBsmtnrhdb\fR \fIsubcommand\fRs are:
.sp
.ne 2
.na
\fB\fBadd\fR\fR
.ad
.sp .6
.RS 4n
Adds a new entry to the \fBtnrhdb\fR database. To add an entry, the
administrator must have the \fBsolaris.network.host.write\fR and
\fBsolaris.network.security.write\fR authorizations.
.RE

.sp
.ne 2
.na
\fB\fBdelete\fR\fR
.ad
.sp .6
.RS 4n
Deletes an entry from the \fBtnrhdb\fR database. To delete an entry, the
administrator must have the \fBsolaris.network.host.write\fR and
\fBsolaris.network.security.write\fR authorizations.
.RE

.sp
.ne 2
.na
\fB\fBlist\fR\fR
.ad
.sp .6
.RS 4n
Lists all entries in the \fBtnrhdb\fR database. To list an entry, the
administrator must have the \fBsolaris.network.host.read\fR and
\fBsolaris.network.security.read\fR authorizations.
.RE

.sp
.ne 2
.na
\fB\fBmodify\fR\fR
.ad
.sp .6
.RS 4n
Modifies an entry in the \fBtnrhdb\fR database. To modify an entry, the
administrator must have the \fBsolaris.network.host.write\fR and
\fBsolaris.network.security.write\fR authorizations.
.RE

.SH OPTIONS
.sp
.LP
The \fBsmtnrhdb\fR authentication arguments, \fIauth_args\fR, are derived from
the \fBsmc\fR arg set. These arguments are the same regardless of which
subcommand you use.
.sp
.LP
The subcommand-specific options, \fIsubcommand_args\fR, must be preceded by the
\fB--\fR option.
.SS "\fIauth_args\fR"
.sp
.LP
The valid \fIauth_args\fR are \fB-D\fR, \fB-H\fR, \fB-l\fR, \fB-p\fR, \fB-r\fR,
and \fB-u\fR; they are all optional. If no \fIauth_args\fR are specified,
certain defaults will be assumed and the user might be prompted for additional
information, such as a password for authentication purposes. These letter
options can also be specified by their equivalent option words preceded by a
double dash. For example, you can use either \fB-D\fR or \fB--domain\fR.
.sp
.ne 2
.na
\fB\fB-D\fR | \fB--domain\fR \fIdomain\fR\fR
.ad
.sp .6
.RS 4n
Specifies the default domain that you want to manage. The syntax of
\fIdomain\fR=\fItype\fR:/\fIhost_name\fR/\fIdomain_name\fR, where \fItype\fR is
\fBdns\fR, \fBldap\fR, or \fBfile\fR; \fIhost_name\fR is the name of the
server; and \fIdomain_name\fR is the name of the domain you want to manage.
.sp
If you do not specify this option, the Solaris Management Console assumes the
\fBfile\fR default domain on whatever server you choose to manage, meaning that
changes are local to the server. Toolboxes can change the domain on a
tool-by-tool basis; this option specifies the domain for all other tools.
.RE

.sp
.ne 2
.na
\fB\fB-H\fR | \fB--hostname\fR \fIhost_name:port\fR\fR
.ad
.sp .6
.RS 4n
Specifies the \fIhost_name\fR and \fIport\fR to which you want to connect. If
you do not specify a \fIport\fR, the system connects to the default port,
\fB898\fR. If you do not specify \fIhost_name:port\fR, the Solaris Management
Console connects to the local host on port \fB898\fR.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR | \fB--rolepassword\fR \fIrole_password\fR\fR
.ad
.sp .6
.RS 4n
Specifies the password for the \fIrole_name\fR. If you specify a
\fIrole_name\fR but do not specify a \fIrole_password\fR, the system prompts
you to supply a \fIrole_password\fR. Passwords specified on the command line
can be seen by any user on the system, hence this option is considered
insecure.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR | \fB--password\fR \fIpassword\fR\fR
.ad
.sp .6
.RS 4n
Specifies the password for the \fIuser_name\fR. If you do not specify a
password, the system prompts you for one. Passwords specified on the command
line can be seen by any user on the system, hence this option is considered
insecure.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR | \fB--rolename\fR \fIrole_name\fR\fR
.ad
.sp .6
.RS 4n
Specifies a role name for authentication. If you do not specify this option, no
role is assumed.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR | \fB--username\fR \fIuser_name\fR\fR
.ad
.sp .6
.RS 4n
Specifies the user name for authentication. If you do not specify this option,
the user identity running the console process is assumed.
.RE

.sp
.ne 2
.na
\fB\fB--\fR\fR
.ad
.sp .6
.RS 4n
This option is required and must always follow the preceding options. If you do
not enter the preceding options, you must still enter the \fB--\fR option.
.RE

.SS "\fIsubcommand_args\fR"
.sp
.LP
\fBNote:\fR Descriptions and other arg options that contain white spaces must
be enclosed in double quotes.
.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.sp .6
.RS 4n
Displays the command's usage statement.
.RE

.sp
.ne 2
.na
\fB\fB-H\fR \fIhostname\fR\fR
.ad
.sp .6
.RS 4n
Specifies the name of the host. For the list subcommand, the hostname argument
is not specified. This is not required if the ipaddress subcommand argument is
specified.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fIipaddress\fR\fR
.ad
.sp .6
.RS 4n
Specifies the \fBIP\fR address of the host. This is not required if the
hostname subcommand argument is specified. This option is not valid with the
\fB-w\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR \fItemplatename\fR\fR
.ad
.sp .6
.RS 4n
Specifies the name of an existing template.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIprefixlen\fR\fR
.ad
.sp .6
.RS 4n
Specifies the prefix length (in bits) of a wildcard representation of the IP
address. The prefix is the left-most portion of the IP address. This option is
valid only with the \fB-w\fR option. For example, when the value of \fB-w\fR
\fIipaddress-wildcard\fR is 192.168.0.0, a \fIprefixlen\fR value of 24
indicates that the wildcard matches all addresses on the 192.168.0 network.
With a \fIprefixlen\fR of 32, the wildcard 192.168.0.0 matches all addresses on
the 192.168.0.0 network.
.RE

.sp
.ne 2
.na
\fB\fB-w\fR \fIipaddress-wildcard\fR\fR
.ad
.sp .6
.RS 4n
Specifies the IP address of the subnet using a wildcard.
.RE

.RS +4
.TP
.ie t \(bu
.el o
One of the following sets of arguments must be specified for subcommand
\fBadd\fR:
.sp
.in +2
.nf
\fB-H\fR \fIhostname\fR \fB-n\fR \fItemplatename\fR |
\fB-i\fR \fIipaddress\fR \fB-n\fR \fItemplatename\fR |
\fB-w\fR \fIipaddress-wildcard\fR \fB-n\fR \fItemplatename\fR [ \fB-p\fR \fIprefixlen\fR ] |
\fB-h\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
.ie t \(bu
.el o
One of the following sets of arguments must be specified for subcommand
\fBmodify\fR:
.sp
.in +2
.nf
\fB-H\fR \fIhostname\fR \fB-n\fR \fItemplatename\fR |
\fB-i\fR \fIipaddress\fR \fB-n\fR \fItemplatename\fR |
\fB-w\fR \fIipaddress-wildcard\fR \fB-n\fR \fItemplatename\fR [ \fB-p\fR \fIprefixlen\fR ] |
\fB-h\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
.ie t \(bu
.el o
One of the following sets of arguments must be specified for subcommand
\fBdelete\fR:
.sp
.in +2
.nf
\fB-H\fR \fIhostname\fR |
\fB-i\fR \fIipaddress\fR |
\fB-w\fR \fIipaddress-wildcard\fR [ \fB-p\fR \fIprefixlen\fR ] |
\fB-h\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
.ie t \(bu
.el o
The subcommand \fBlist\fR takes the following argument:
.sp
.in +2
.nf
\fB-h\fR
.fi
.in -2
.sp

.RE
.SH EXAMPLES
.LP
\fBExample 1 \fRSpecifying the Template Name for a Wildcard IP Address
.sp
.LP
The admin role specifies the template name, \fBcipso_lan\fR, for a series of
hosts that use the IP address wildcard \fB192.168.113.0\fR on the local file
system. Since no authorization arguments were specified, the administrator
connects to port 898 of the local host on the local server with the file domain
type, which are the defaults. The administrator is prompted for the admin
password.

.sp
.in +2
.nf
$ \fBusr/sadm/bin/smtnrhdb add -- -w 192.168.113.0 -n cipso_lan\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRDeleting an Entry in the \fBtnrhdb\fR Database
.sp
.LP
The admin role connects to port 898 (which happens to be the default) of the
LDAP server and deletes a host entry from the database by specifying its IP
address, \fB192.168.113.8\fR. Since the domain was not specified, the file
domain type and local server are used by default. The administrator is prompted
for the admin password.

.sp
.in +2
.nf
# \fB/usr/sadm/bin/smtnrhdb delete \
-D ldap:/example.domain -i 192.168.113.8\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRAdding a Subnet to the \fBtnrhdb\fR Database
.sp
.LP
The following command adds all the addresses on the 192.168.55.0 subnet, from
192.168.55.1 to 192.168.55.255, to the \fBtnrhdb\fR database:

.sp
.in +2
.nf
# \fB/usr/sadm/bin/smtnrhdb add \e
-D file:/machine1.ExampleCo.COM/machine1.ExampleCo.COM \e
 -- -w 192.168.55.0 -n cipso\fR
Authenticating as user: \fBroot\fR
Type /? for help, pressing <enter> accepts the default denoted by [ ]
Please enter a string value for: password \fB::\fR
Loading Tool: com.exampleco.admin.hostmgr.cli.smtnrhdb.HostMgrTnrhdbCli
from machine1.ExampleCo.COM
Login to machine1.ExampleCo.COM as user root was successful.
Download of com.exampleco.admin.hostmgr.cli.smtnrhdb.HostMgrTnrhdbCli
from machine1.ExampleCo.COM
was successful.
.fi
.in -2
.sp

.LP
\fBExample 4 \fRAdding Subnet 192.168.0 to the \fBtnrhdb\fR Database
.sp
.LP
The following command adds all the addresses on the 192.168.0 subnet, from
192.168.0.1 to 192.168.0.255 to the \fBtnrhdb\fR database. The prefix, 24,
indicates that the first 24 bits (192.168.0) are fixed. Only the final zero is
a wildcard.

.sp
.in +2
.nf
# \fB/usr/sadm/bin/smtnrhdb add \e
-D file:/machine1.ExampleCo.COM/machine1.ExampleCo.COM \e
 -- -w 192.168.0.0 -p 24 -n cipso\fR

Login to machine1.ExampleCo.COM as user root was successful.
Download of com.exampleco.admin.hostmgr.cli.smtnrhdb.HostMgrTnrhdbCli
from machine1.ExampleCo.COM was successful.
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.sp .6
.RS 4n
Invalid command syntax. A usage message displays.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.sp .6
.RS 4n
An error occurred while executing the command. An error message displays.
.RE

.SH FILES
.sp
.LP
The following files are used by the \fBsmtnrhdb\fR command:
.sp
.ne 2
.na
\fB\fB/etc/security/tsol/tnrhdb\fR\fR
.ad
.sp .6
.RS 4n
Trusted network remote-host database.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBsmc\fR(1M), \fBnetmasks\fR(4), \fBattributes\fR(5)
.sp
.LP
\fISystem Administration Guide: Security Services\fR
.SH NOTES
.sp
.LP
The functionality described on this manual page is available only if the system
is configured with Trusted Extensions.