DEFINE SERVER (Define a server for server-to-server communications)

Use this command to define a server to use functions such as virtual volumes, node replication, command routing, and LAN-free data movement, among others.

Use this command to define a server for the following functions:

Enterprise configuration
Enterprise event logging
Command routing
Virtual volumes
LAN-free data movement
Node replication
Data movement by using z/OS® media server
Status monitoring of remote servers
Alert monitoring of remote servers
Server-to-server export

If you use an LDAP directory server to authenticate passwords, any target servers must be configured for LDAP-authenticated passwords. Data that is replicated from a node that authenticates with an LDAP directory server is inaccessible if the target replication server is not properly configured. If your target replication server is not configured, replicated data from an LDAP node can make it to the target server. But the target replication server must be configured to use LDAP if you want to access the data.

The use of virtual volumes is not supported when the source server and the target server are on the same Tivoli® Storage Manager server.

This command also is used to define a Tivoli Storage Manager storage agent as if it were a server.

Privilege class

To issue this command, you must have system privilege.

Syntax

For:

Command routing
Status monitoring of remote servers
Alert monitoring of remote servers
Server-to-server export

Tip: Command routing uses the ID and the password of the administrator who is issuing the command.


>>-DEFine--SERver--server_name--HLAddress--=--ip_address-------->

>--LLAddress--=--tcp_port--+----------------------+------------->
                           '-COMMmethod--=--TCPIP-'   

>--+-------------+--+-----------------------------+------------><
   '-URL--=--url-'  '-DESCription--=--description-'

Syntax

For:

Enterprise configuration
Enterprise event logging
Storage agent
Node replication source and target servers
z/OS media server


>>-DEFine--SERver--server_name--SERVERPAssword--=--password----->

>--HLAddress--=--ip_address--LLAddress--=--tcp_port------------->

>--+----------------------+--+-------------+-------------------->
   '-COMMmethod--=--TCPIP-'  '-URL--=--url-'   

>--+-----------------------------+------------------------------>
   '-DESCription--=--description-'   

                          (1)     
   .-CROSSDEFine--=--No-------.   
>--+--------------------------+--------------------------------->
   '-CROSSDEFine--=--+-No--+--'   
                     '-Yes-'      

                               (2)                          
   .-VALIdateprotocol--=--No-------.  .-SSL--=--No------.   
>--+-------------------------------+--+-----------------+------><
   '-VALIdateprotocol--=--+-No--+--'  '-SSL--=--+-No--+-'   
                          '-All-'               '-Yes-'

Notes:

For AIX®, Linux, Solaris, and Windows: The CROSSDEFINE parameter does not apply to storage agent definitions.
The VALIDATEPROTOCOL parameter applies only to storage agent definitions.

Syntax for virtual volumes


>>-DEFine--SERver--server_name--PAssword--=--password----------->

>--HLAddress--=--ip_address--LLAddress--=--tcp_port------------->

>--+----------------------+--+-------------+-------------------->
   '-COMMmethod--=--TCPIP-'  '-URL--=--url-'   

>--+-------------------------+--+------------------------+------>
   '-DELgraceperiod--=--days-'  '-NODEName--=--node_name-'   

                                    .-SSL--=--No------.   
>--+-----------------------------+--+-----------------+--------><
   '-DESCription--=--description-'  '-SSL--=--+-No--+-'   
                                              '-Yes-'

Parameters

server_name (Required)

Specifies the name of the server. This name must be unique on the server. The maximum length of this name is 64 characters.

For server-to-server event logging, library sharing, and node replication, you must specify a server name that matches the name that was set by issuing the SET SERVERNAME command at the target server.

PAssword

Specifies the password that is used to sign on to the target server for virtual volumes. If you specify the NODENAME parameter, you must specify the PASSWORD parameter. If you specify the PASSWORD parameter but not the NODENAME parameter, the node name defaults to the server name specified with the SET SERVERNAME command.

SERVERPAssword

Specifies the password of the server you are defining. This password must match the password that is set by the SET SERVERPASSWORD command. This parameter is required for enterprise configuration and server-to-server event logging functions.

HLAddress (Required)

Specifies the IP address (in dotted decimal format) of the server.

Do not use the loopback address as the value of this parameter. Virtual volumes are not supported when the source server and the target server are the same Tivoli Storage Manager server.

LLAddress (Required)

Specifies the low-level address of the server. This address is usually the same as the address in the TCPPORT server option of the target server. When SSL=YES, the port must already be designated for SSL communications on the target server.

COMMmethod

Specifies the communication method that is used to connect to the server. This parameter is optional.

URL

Specifies the URL address of this server. The parameter is optional.

DELgraceperiod

Specifies a number of days that an object remains on the target server after it was marked for deletion. You can specify a value 0 - 9999. The default is 5. This parameter is optional.

NODEName

Specifies a node name to be used by the server to connect to the target server. This parameter is optional. If you specify the NODENAME parameter, you must also specify the PASSWORD parameter. If you specify the PASSWORD parameter but not the NODENAME parameter, the node name defaults to the server name specified with the SET SERVERNAME command.

DESCription

Specifies a description of the server. The parameter is optional. The description can be up to 255 characters. Enclose the description in quotation marks if it contains blank characters.

CROSSDEFine

Specifies whether the server that is running this command defines itself to the server that is being specified by this command. This parameter is optional.

Important: This parameter does not apply to storage agent definitions.

If this parameter is included, you must also issue the SET SERVERNAME, SET SERVERPASSWORD, SET SERVERHLADDRESS, SET CROSSDEFINE, and SET SERVERLLADDRESS commands. The default is NO.

Remember:

For replication operations, the names of the source and target replication servers must match the names that you specify in this command.
CROSSDEFINE can be used with SSL=YES if all of the conditions that are specified for the SSL=YES parameter are in place on the source and target server.

You can specify one of the following values:

No: Cross definition is not completed.
Yes: Cross definition is completed.

VALIdateprotocol

Specify a cyclic redundancy check to validate the data that is sent between the storage agent and Tivoli Storage Manager server. The parameter is optional. The default is NO. You can specify one of the following values:

No: Specifies that data validation is not completed on any data that is sent between the storage agent and server.
All: Specifies that data validation is completed on all client file data, client file metadata, and Tivoli Storage Manager server metadata that is sent between the storage agent and server. This mode affects performance as more resources are required to calculate and compare CRC values between the storage agent and the server.

SSL

Specifies the communication mode of the server. The default is NO. You can specify one of the following values:

No

Specifies that unencrypted communication with the specified server occurs over a TCP/IP session without SSL.

Yes

Specifies an SSL session for communication with the specified server. The following conditions apply if you specify YES:

Before you start the servers, self-signed certificates of the partner servers must be in the key database file (cert.kdb) of each of the servers.
You can define multiple server names with different parameters for the same target server.
SSL support is active if the server options file contains the SSLTCPPORT or SSLTCPADMINPORT option or if a server is defined with SSL=YES at startup.
Storage agents can issue the DSMSTA SETSTORAGESERVER command and include the STAKEKEYDBPW and SSL parameters to create the key database.
If third-party certificates are used, the CA (certificate authority) certificate must be kept in the key database of the partner server. If you upgrade from a release earlier than V6.3.0 and have a key database file in your instance directory, update it to allow third-party certificates. To update the key database file, issue the following command:
```
gsk8capicmd_64 -keydb -convert -populate 
-db cert.kdb -pw passwordofkeydatabasefile
```
To issue the command on a Windows server, set the path to include x:\Program Files\IBM\gsk8\bin;x:\Program Files\IBM\gsk8\lib64, where x is the system drive.

Example: Set up two servers to use SSL to communicate

You must set up two servers to use SSL to communicate. The server addresses are as follows:

ServerA is at bfa.tucson.ibm.com
ServerB is at bfb.tucson.ibm.com

Complete the following steps to set up the two servers for SSL:

Specify options SSLTCPPORT 1542 and TCPPORT 1500 for both servers in the dsmserv.opt option file.
Start both servers and run the following command to set up the key database file password:
```
SET SSLKEYRINGPW newpw UPDATE=Y
```
Shut down both servers to import the cert256 partner certificate. For ServerA, the certificate is in the /tsma instance directory. For ServerB, the certificate is in the /tsmb instance directory.
Start both servers. The /tsma/cert256.arm file is copied to /tsmb/cert256.bfa.arm on the bfb.tucson.ibm.com address. The /tsmb/cert256.arm file is copied to /tsmb/cert256.bfb.arm on the bfa.tucson.ibm.com address.

Issue the following command:

From ServerA:

gsk8capicmd_64 -cert -add -db cert.kdb -pw newpw -format ascii 
-label "bfb" -file /tsma/cert256.bfb.arm

From ServerB:

gsk8capicmd_64 -cert -add -db cert.kdb -pw newpw -format ascii 
-label "bfa" -file /tsmb/cert256.bfa.arm

From each server, you can view the certificates in the key database by issuing the following command:

gsk8capicmd_64 -cert -list -db cert.kdb -pw newpw

Restart the servers.

Issue the appropriate DEFINE SERVER command. For ServerA, issue the following example command:

DEFINE SERVER BFB hla=bfb.tucson.ibm.com lla=1542 
serverpa=passwordforbfb SSL=YES

For ServerB, issue the following example command:

DEFINE SERVER BFA hla=bfa.tucson.ibm.com lla=1542 
serverpa=passwordforbfa SSL=YES

If you do not use SSL, issue the following example DEFINE SERVER command on ServerA:

DEFINE SERVER BFBTCP hla=bfb.tucson.ibm.com lla=1500 
serverpa=passwordforbfb SSL=NO

If you do not use SSL, issue the following example DEFINE SERVER command on ServerB:

DEFINE SERVER BFATCP hla=bfa.tucson.ibm.com lla=1500 
serverpa=passwordforbfa SSL=NO

Example: Define a target server

A target server has a high-level address of 9.116.2.67 and a low-level address of 1570. Define that target server to the source server, name it SERVER2, and set the password to SECRET. Specify that objects remain on the target server for seven days after they are marked for deletion.

define server server2 password=secret 
  hladdress=9.115.3.45 lladdress=1570 delgraceperiod=7

Example: Define a server to receive commands from other servers

Define a server that can receive commands that are routed from other servers. Name the server WEST_COMPLEX. Set the high-level address to 9.172.12.35, the low-level address to 1500, and the URL address to http://west_complex:1580/.

define server west_complex 
hladdress=9.172.12.35 lladdress=1500 
url=http://west_complex:1580/

Example: Cross-define two servers

Use cross definition to define SERVER_A and SERVER_B.

On SERVER_B, specify the server name, password, and high- and low-level addresses of SERVER_B. Specify that cross defining is allowed.
```
set servername server_b
set serverpassword mylife
set serverhladdress 9.115.20.80
set serverlladdress 1860
set crossdefine on
```

On SERVER_A, specify the server name, password, and high- and low-level addresses of SERVER_A.

set servername server_a
set serverpassword yourlife
set serverhladdress 9.115.20.97
set serverlladdress 1500

On SERVER_A, define SERVER_B:

define server server_b hladdress=9.115.20.80 lladdress=1860
serverpassword=mylife crossdefine=yes

Related commands

Table 1. Commands related to DEFINE SERVER
Command	Description
DEFINE DEVCLASS	Defines a device class.
DEFINE PATH	Define a path when the destination is a z/OS media server.
DELETE DEVCLASS	Deletes a device class.
DELETE FILESPACE	Deletes data associated with client file spaces. If a file space is part of a collocation group and you remove the file space from a node, the file space is removed from the collocation group.
DELETE SERVER	Deletes the definition of a server.
QUERY NODE	Displays partial or complete information about one or more clients.
QUERY SERVER	Displays information about servers.
RECONCILE VOLUMES	Reconciles source server virtual volume definitions and target server archive objects.
REGISTER NODE	Defines a client node to the server and sets options for that user.
REMOVE NODE	Removes a client from the list of registered nodes for a specific policy domain.
SET CROSSDEFINE	Specifies whether to cross define servers.
SET SERVERNAME	Specifies the name by which the server is identified.
SET SERVERHLADDRESS	Specifies the high-level address of a server.
SET SERVERLLADDRESS	Specifies the low-level address of a server.
SET SERVERPASSWORD	Specifies the server password.
SET REPLSERVER	Specifies a target replication server.
UPDATE DEVCLASS	Changes the attributes of a device class.
UPDATE NODE	Changes the attributes associated with a client node.
UPDATE PATH	Define a path when the destination is a z/OS media server.
UPDATE SERVER	Updates information about a server.