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
  • AIX operating systemsLinux operating systemsData 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.
Read syntax diagramSkip visual syntax diagram
>>-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
  • AIX operating systemsLinux operating systemsz/OS media server
Read syntax diagramSkip visual syntax diagram
>>-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:
  1. For AIX®, Linux, Solaris, and Windows: The CROSSDEFINE parameter does not apply to storage agent definitions.
  2. The VALIDATEPROTOCOL parameter applies only to storage agent definitions.

Syntax for virtual volumes

Read syntax diagramSkip visual syntax diagram
>>-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.
AIX operating systemsLinux operating systemsSun Solaris operating systemsWindows operating systemsImportant: 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

    Windows operating systemsTo 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: Complete the following steps to set up the two servers for SSL:
  1. Specify options SSLTCPPORT 1542 and TCPPORT 1500 for both servers in the dsmserv.opt option file.
  2. Start both servers and run the following command to set up the key database file password:
    SET SSLKEYRINGPW newpw UPDATE=Y
  3. 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.
  4. 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.
  5. 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
  6. Restart the servers.
  7. 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.
  1. 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
  2. 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
  3. 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.
AIX operating systemsLinux operating systemsDEFINE PATH AIX operating systemsLinux operating systemsDefine 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.
AIX operating systemsLinux operating systemsUPDATE PATH AIX operating systemsLinux operating systemsDefine a path when the destination is a z/OS media server.
UPDATE SERVER Updates information about a server.