NAME

host  — A dcecp task object that manages host information in a DCE cell

SYNOPSIS

host catalog  [cell_name]  [simplename ]

host configure host_name cell cell_name secmaster master_security_server_name cds cds_server_name password password  [admin admin_principal]  {client  | server  }

host help  [operation | verbose  ]

host operations

host ping host_name

host show  [host_name]

host start  [host_name]

host stop  [host_name]  [force ]

host unconfigure host_name  [force ]

Arguments

cell_nameThe name of a single cell to operate on.  The name must be a fully qualified cell name such as either of the following:

/.../their_cell.goodco.com
/.:

host_nameThe name of a single host to operate on.  Some host commands accept both fully qualified names (as in /.../cellname/hosts/hostname) and cell relative names (as in hosts/hostname), while others will accept only fully qualified names.  See individual command descriptions in Operations for details. 

operationThe name of the host  operation for which to display help information. 

Description

The host  task object represents DCE processes running on a machine in (or to be added to) a DCE cell.  The host  task object allows administrators to configure and start DCE on machines easily. 

The host  task object can configure and start the core DCE services on a client machine.  The services include the DCE daemon (dced ), the Cell Directory Service (CDS) client (cdsadv ), the Distributed Time Service (DTS) daemon (dtsd ), and the audit daemon (auditd ).  The argument to this command is the DCE name of a host to operate on.  If an argument is omitted, the command operates on the local host, if possible.  The behavior of commands operating locally may differ from the behavior of commands operating remotely, with more operations performed on the local host than may be possible remotely.  See Operations for details. 

Currently only a client can be configured using the host  command. 

Note:  All operations of the host  task object are not fully supported in this release. 

Errors

A representative list of errors that might be returned is not shown here.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

Operations

host catalog

Returns a list of names of hosts in the cell.  The syntax is as follows:

host catalog [cell_name] [simplename ]

The catalog  operation returns a list of names of hosts in the cell.  By default, the names are fully qualified.  Use the simplename  option to return cell-relative names.  The optional cell_name argument specifies a cell to operate in. 

Privileges Required

You must have r (read) permission to the /.:/hosts directory in CDS. 

Examples

The following example lists the full names of all the DCE hosts that have entries in the CDS /.:/hosts directory in the local cell:

dcecp> host catalog
/.../my_cell.goodco.com/hosts/alpha
/.../my_cell.goodco.com/hosts/beta
/.../my_cell.goodco.com/hosts/gamma
dcecp> 

The following example lists the simple names of all the DCE hosts that have entries in the CDS /.:/hosts directory in the local cell:

dcecp> host catalog -simplename
hosts/alpha
hosts/beta
hosts/gamma
dcecp>  

host configure

Configures a single machine named by the argument into an existing DCE cell.  The syntax is as follows:

host configure host_name cell  cell_name
secmaster  master_security_server_name cds  cds_server_name password  password
[admin  admin_principal] {client  | server }

Options

cell  cell_name
Specifies the name of the cell in which the host is to be configured.  The format is /.../cellname. 

clientConfigures the host as a DCE client machine.  The machine will be configured to run dced  (including the secval  service), a DTS clerk (dtsd ), cdsadv , and auditd . 

serverConfigures the host as a DCE server machine. This option is currently not supported. 

secmaster  master_security_server_name
Specifies the hostname of the security master server in the form hostname. 

cds  cds_server_name
Specifies the hostname of any CDS server in the form hostname. 

password  password
Specifies the password of the cell administrator.

admin  admin_principal
Optionally specifies the principal name of the cell administrator principal.  It defaults to cell_admin . 

The configure operation configures a single machine named by the host_name argument into a DCE cell.  The cell must already exist and must have a security and naming service operating.  The DCE software must be installed on the machine.  The host_name argument is the name of the local host machine without the cell name prepended, as in the following:

hosts/hostname

This operation returns an empty string on success. 

Privileges Required

You must have root authority. 

Examples

The following example configures host hydra in the cell /.../my_cell.goodco.com:

dcecp> host configure  hosts/hydra -client \
> -cell my_cell.goodco.com -password fstzkl -secmaster scylla \
> -cds charybdis
dcecp> 

host help

Returns help information about the host  task object and its operations.  The syntax is as follows:

host help [operation | verbose ]

Options

verboseDisplays information about the host  task object. 

Used without an argument or option, the host help  command returns brief information about each host  operation.  The optional operation argument is the name of an operation about which you want detailed information.  Alternatively, you can use the verbose  option for more detailed information about the host  task object itself. 

Privileges Required

No special privileges are needed to use the host help command. 

Examples

dcecp> host help
catalog             Returns a list of configured hosts in the cell.
configure           Configures a host into the cell as a client or server.
ping                Determines if DCE is responding on the specified host.
show                Returns all DCE processes configured on the specified host.
start               Starts DCE on the specified host.
stop                Stops DCE on the specified host.
unconfigure         Removes the host from the name and security databases.
help                Prints a summary of command-line options.
operations          Returns a list of the valid operations for this command.
dcecp>  

host operations

Returns a list of the operations supported by the host  task object.  The syntax is as follows:

host operations

The list of available operations is in alphabetical order except for help  and operations, which are listed last. 

Privileges Required

No special privileges are needed to use the host operations command. 

Examples

dcecp> host operations
catalog configure ping show start stop unconfigure help operations
dcecp> 

host ping

Tests whether DCE processes are accessible from the network.  The syntax is as follows:

host ping host_name

The ping  operation tests whether DCE processes are accessible from the network.  It contacts the endpoint mapper (either rpcd  or dced , whichever listens on port 135) on the specified host.  The host_name argument is the fully qualified name of the host to ping as in the following:

/.:/hosts/hostname

The operation returns 1 if the host responds, 0 if it does not. 

Privileges Required

No special privileges are required for the host ping  command. 

Examples

The following example pings host hydra:

dcecp> host ping /.:/hosts/hydra
1
dcecp> 

host show

The show  operation is not currently implemented. 

Returns a list describing all processes that are configured to run on the specified host.  The syntax is as follows:

host show [host_name]

The show  operation returns a list describing all processes that are configured to run on the specified host.  The optional host_name argument is the fully qualified or cell-relative name of a DCE host, such as hosts/name or /.:/hosts/name.  If not given, the local host is assumed.  The returned list contains the following:

   •The server name as output by the server catalog -simplename command. 

   •One of the tokens running or notrunning. 

   •An optional server-specific comment such as master or replica for a security server and clerk or server for a DTS server. 

If the DCE daemons on the specified host were not started by the dcecp server command, the output of this command will not be as expected. 

Privileges Required

You must have r (read) permission to the config/srvrconf container object on the specified host. 

Examples

dcecp> host show hosts/hydra
{dced running}
{cdsd running}
{cdsadv running}
{secd running master}
{auditd notrunning}
{dtsd running clerk}
dcecp>

host start

Starts all DCE processes on the specified host.  The syntax is as follows:

host start [host_name]

The start operation starts all DCE processes on the specified host.  This command depends on dced  being running on the specified host; that is, it may not be used to start DCE on systems that use versions prior to Version 1.1.  The processes that are started are all those listed in the server configuration data stored in the dced  on the specified host with the boot or explicit values of the starton attribute.  You can add servers to the server configuration data by using the server create  command.  The host configure  command adds certain servers to the configuration data automatically. 

The host_name argument is the fully qualified or cell-relative name of the host to operate on, as in the following:

/.:/hosts/hostname
hosts/hostname

Without the host_name argument, dced  is started on the local host first, which requires the appropriate local permissions (usually root).  If a host name is specified, dced  must be running on that host.  Before starting any host, make sure that a security server and a CDS server are both running somewhere in the cell.  This operation returns an empty string on success. 

Privileges Required

You must have x (execute) permission to the config/srvrconf container object on the specified host. 

Examples

The following example starts all DCE processes on host hydra:

dcecp> host start hosts/hydra
dcecp>  

host stop

Stops all DCE processes on the specified host.  The syntax is as follows:

host stop [host_name] [force ]

Options

forceOptionally, specifies that any servers that fail to stop normally should be stopped using a server stop -method hard command. 

The stop operation stops running DCE processes on the specified host.  This command depends on dced  being on the specified host, that is, it may not be used to stop DCE on systems that use versions prior to Version 1.1.  The host_name argument is the fully qualified or cell-relative name of the host to operate on, as in

/.:/hosts/hostname.
hosts/hostname

Processes are stopped as follows:

   •All servers listed in the server execution data are stopped.  Servers implementing DCE core services are stopped last, in the appropriate order.  If servers were not started as srvrexec objects, they will not be stopped. 

   •If any servers fail to stop, and the force  option was specified, those servers are stopped by the command server stop -method hard. 

This operation returns an empty string on success. 

Privileges Required

You must have s (stop) permission on the config/srvrexec object for each server to be stopped. 

Examples

The following example stops host hydra:

dcecp> host stop hosts/hydra
dcecp>  

host unconfigure

Unconfigures a specified host from a cell.  The syntax is as follows:

host unconfigure host_name [force ]

Options

forceOptionally specifies that any errors that occur during an unconfigure operation are to be ignored and the unconfigure operation should continue. 

The unconfigure operation unconfigures a specified host from a cell.  To unconfigure a cell, the operation deletes the following:

   •All objects, directories and links from /.:/hosts/hostname including the directory itself

   •All principal names beginning with hosts/hostname, but not accounts with the same names

The unconfigure operation takes the fully qualified name of a host to unconfigure as an argument, as in the following:

/hosts/hostname

This operation returns an empty string on success. 

Privileges Required

You must have the appropriate permission to delete CDS objects and directories.  You must also have the appropriate permission to delete principals from the registry.  Refer to the appropriate reference page on each object for more details. 

Examples

The following example unconfigures host hydra from the cell:

dcecp> host unconfigure hosts/hydra
dcecp> 

Related Information

Commands: dcecp(8dce), account(8dce), aud(8dce), directory(8dce), dts(8dce), registry(8dce), server(8dce).