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, LAN-free data movement, and data offloads, 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
  • Linux operating systemsAIX operating systemsData movement by using z/OS® media server
  • Status monitoring of remote servers
  • Alert monitoring of remote servers
  • Server-to-server export
  • Linux operating systemsWindows operating systemsIBM Spectrum Protect Plus data offload

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 IBM Spectrum Protect server.

This command is used to define an IBM Spectrum Protect 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 diagramDEFineSERverserver_name HLAddress=ip_address LLAddress=tcp_port COMMmethod=TCPIPURL=urlDESCription=descriptionSSL=NoSSL=NoYesSESSIONSECurity=TRANSitionalSESSIONSECurity=STRictTRANSitional

Syntax

For:
  • Enterprise configuration
  • Enterprise event logging
  • Storage agent
  • Node replication source and target servers
  • Linux operating systemsAIX operating systemsz/OS media server
Read syntax diagramSkip visual syntax diagram DEFine SERver server_name SERVERPAssword = password HLAddress = ip_address LLAddress = tcp_port COMMmethod=TCPIPURL=urlDESCription=descriptionCROSSDEFine=No1CROSSDEFine=NoYes2VALIdateprotocol=NoVALIdateprotocol=NoAllSSL=NoSSL=NoYesSESSIONSECurity=TRANSitionalSESSIONSECurity=STRictTRANSitionalTRANSFERMethod=TcpipTRANSFERMethod=TcpipFasp3
Notes:
  • 1 The CROSSDEFINE parameter does not apply to storage agent definitions.
  • 2 The VALIDATEPROTOCOL parameter is deprecated and applies only to storage agent definitions.
  • 3 The TRANSFERMETHOD parameter is available only on Linux x86_64 operating systems.

Syntax for virtual volumes

Read syntax diagramSkip visual syntax diagramDEFineSERverserver_name PAssword=password HLAddress=ip_address LLAddress=tcp_port COMMmethod=TCPIPURL=urlDELgraceperiod=daysNODEName=node_nameDESCription=descriptionSSL=NoSSL=NoYesSESSIONSECurity=TRANSitionalSESSIONSECurity=STRictTRANSitional
Linux operating systemsWindows operating systems

Syntax for object agents

For object agents offloading data from IBM Spectrum Protect Plus to IBM Spectrum Protect

Read syntax diagramSkip visual syntax diagram DEFine SERver server_name HLAddress = ip_address LLAddress = tcp_port OBJECTAgent=NoOBJECTAgent=NoYesCOMMmethod=TCPIPURL=urlDESCription=description

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.
Linux operating systemsWindows operating systemsRestriction: Server-to-server event logging, library sharing, and node replication do not apply to object agent definitions.
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 that is specified with the SET SERVERNAME command. The minimum length of the password is 8 characters unless a different value is specified by using the SET MINPWLENGTH command. The maximum length of the password is 64 characters.
Linux operating systemsWindows operating systemsRestriction: This parameter does not apply to object agent definitions.
SERVERPAssword
Specifies the password of the server that 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. The minimum length of the password is 8 characters unless a different value is specified by using the SET MINPWLENGTH command. The maximum length of the password is 64 characters.
Linux operating systemsWindows operating systemsRestriction: This parameter does not apply to object agent definitions.
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 IBM Spectrum Protect 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. The range of values is 1 - 32767.
Linux operating systemsWindows operating systemsOBJECTAgent
Linux operating systemsWindows operating systems

Specifies that this server is an agent for object storage on the target server.

You can specify one of the following values:
No
Specifies that this server is not an object agent. The default is NO.
Yes (Required for object agents)
Specifies that this server is an object agent and that a configuration file will be created in the server instance directory.
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.
Linux operating systemsWindows operating systemsRestriction: This parameter does not apply to object agent definitions.
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.
Linux operating systemsWindows operating systemsRestriction: This parameter does not apply to object agent definitions.
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.
Restriction: This parameter does not apply to storage agent or object 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 (deprecated)

Specifies whether a cyclic redundancy check validates the data that is sent between the storage agent and IBM Spectrum Protect server. The parameter is optional. The default is NO.

Important: Beginning with IBM Spectrum Protect Version 8.1.2 and Tivoli® Storage Manager Version 7.1.8, validation that was enabled by this parameter is replaced by the TLS 1.2 protocol, which is enforced by the SESSIONSECURITY parameter. The VALIDATEPROTOCOL parameter is ignored. Update your configuration to use the SESSIONSECURITY parameter.
Linux operating systemsWindows operating systemsRestriction: This parameter does not apply to object agent definitions.
SSL
Specifies the communication mode of the server. The default is NO.
Important: Beginning in IBM Spectrum Protect V8.1.2 and Tivoli Storage Manager V7.1.8, the SSL parameter uses SSL to encrypt some communication with the specified server even if SSL=NO.
Linux operating systemsWindows operating systemsRestriction: This parameter does not apply to object agent definitions.
The following conditions and considerations apply when you specify the SSL parameter:
  • 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.
  • Storage agents can issue the DSMSTA SETSTORAGESERVER command and include the SSL parameter to create the key database.

You can specify one of the following values:

No
Specifies an SSL session for all communication with the specified server, except when the server is sending or receiving object data. Object data is sent and received by using TCP/IP. By choosing not to encrypt the object data, server performance is similar to communication over a TCP/IP session and the session is secure.
Yes
Specifies an SSL session for all communication with the specified server, even when the server is sending and receiving object data.
SESSIONSECurity
Specifies whether the server that you are defining must use the most secure settings to communicate with an IBM Spectrum Protect server. This parameter is optional.
Linux operating systemsWindows operating systemsRestriction: This parameter does not apply to object agent definitions.

You can specify one of the following values:

STRict
Specifies that the strictest security settings are enforced for the server that you are defining. The STRICT value uses the most secure communication protocol available, which is currently TLS 1.2. The TLS 1.2 protocol is used for SSL sessions between the specified server and an IBM Spectrum Protect server.
To use the STRICT value, the following requirements must be met to ensure that the specified server can authenticate with the IBM Spectrum Protect server:
  • Both the server that you are defining and the IBM Spectrum Protect server must be using IBM Spectrum Protect software that supports the SESSIONSECURITY parameter.
  • The server that you are defining must be configured to use the TLS 1.2 protocol for SSL sessions between itself and the IBM Spectrum Protect server.
Servers set to STRICT that do not meet these requirements are unable to authenticate with the IBM Spectrum Protect server.
TRANSitional
Specifies that the existing security settings are enforced for the server. This is the default value. This value is intended to be used temporarily while you update your security settings to meet the requirements for the STRICT value.

If SESSIONSECURITY=TRANSITIONAL and the server has never met the requirements for the STRICT value, the server will continue to authenticate by using the TRANSITIONAL value. However, after a server meets the requirements for the STRICT value, the SESSIONSECURITY parameter value automatically updates from TRANSITIONAL to STRICT. Then, the server can no longer authenticate by using a version of the client or an SSL/TLS protocol that does not meet the requirements for STRICT. In addition, after a server successfully authenticates by using a more secure communication protocol, the server can no longer authenticate by using a less secure protocol. For example, if a server that is not using SSL is updated and successfully authenticates by using TLS 1.2, the server can no longer authenticate by using no SSL protocol or TLS 1.1. This restriction also applies when you use functions such as virtual volumes, command routing, or server-to-server export, when a node or administrator authenticates to the IBM Spectrum Protect server as a node or administrator from another server.

Linux operating systemsTRANSFERMethod
Linux operating systemsSpecifies the method that is used for server-to-server data transfer. This parameter is optional.
Linux operating systemsWindows operating systemsRestriction: This parameter does not apply to object agent definitions.
You can specify one of the following values:
Tcpip
Specifies that TCP/IP is used to transfer data. This is the default.
Fasp
Specifies that IBM Aspera® Fast Adaptive Secure Protocol (FASP®) technology is used to transfer data. Aspera FASP technology can help you optimize data transfer in a wide area network (WAN).
Restrictions:
  • Before you enable Aspera FASP technology, determine whether the technology is appropriate for your system environment and install the appropriate licenses. For instructions, see Determining whether Aspera FASP technology can optimize data transfer in your system environment. If the licenses are missing or expired, data transfer operations fail.
  • If WAN performance meets your business needs, do not enable Aspera FASP technology.
  • If you specify TRANSFERMETHOD=FASP on the PROTECT STGPOOL or REPLICATE NODE command, that value overrides the TRANSFERMETHOD parameter on the DEFINE SERVER and UPDATE SERVER commands.

Example: Set up two servers to use SSL to communicate (manual configuration)

Tip: If both servers are using IBM Spectrum Protect V8.1.2 or later software or Tivoli Storage Manager V7.1.8 software, SSL is automatically configured between the servers and manual configuration is not required.
If both servers are not using V7.1.8 or V8.1.2 or later software, you must manually configure the 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:
  1. Specify option TCPPORT 1500 for both servers in the dsmserv.opt option file.
  2. Start both servers.
  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 -stashed -format ascii 
-label "bfb" -file /tsma/cert256.bfb.arm
    • From ServerB:
      gsk8capicmd_64 -cert -add -db cert.kdb -stashed -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 -stashed
  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 server to communicate with another server by using strict session security

Define a server name of SERVER1 to use the strictest security settings to authenticate with the IBM Spectrum Protect server.
define server server1 sessionsecurity=strict

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 the target server SERVER2, and set the password to SECRETPASSWORD. Specify that objects remain on the target server for seven days after they are marked for deletion.
define server server2 password=secretpassword 
  hladdress=9.116.2.67 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 mylifepwd
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 yourlifepwd
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=mylifepwd crossdefine=yes

Related commands

Table 1. Commands related to DEFINE SERVER
Command Description
DEFINE DEVCLASS Defines a device class.
Linux operating systemsAIX operating systemsLinux operating systemsAIX operating systemsDEFINE PATH Linux operating systemsAIX 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 that are associated with a client node.
Linux operating systemsAIX operating systemsUPDATE PATH Linux operating systemsAIX operating systemsDefine a path when the destination is a z/OS media server.
UPDATE SERVER Updates information about a server.