open - UDM Command

Syntax

open [primary={*|local|host-name} [port=broker-port] [user=username [pwd=password]] [codepage=codepage] [{file=filename | xfile=filename [key=key]}] [verserial=serial number|no] [verhost=yes|no|host name]
secondary=host-name [port=broker-port] [user=username [pwd=password]] [codepage=codepage] [{file=filename | [xfile=filename [key=key]}] [verserial=serial number|no] [verhost=yes|no]
[encrypt=yes|no|cipher] [compress=compression-method] [nft=yes|no] [comment=text] [tt=direct|deferred] [minsslprotocol=tls1_0|tls1_2|tls1_3]


Description

The open command opens a UDM transfer session: two-party or three-party.
 


 

Each transfer session has a primary server and a secondary server. These servers are given logical names (primary and secondary) by the user.

For a two-party transfer session, a UDM Manager acts as the primary server, and its logical name (primary) is set to:

  • * or local as the host name, if the logical name of the secondary server is specified.

Optionally, an open command can specify only a secondary server logical name (secondary), which implies a two-party transfer. In this case, the primary server (the UDM Manager) automatically is assigned local as the logical name.

For a three-party transfer session, a UDM Server is the primary server, and its logical name (primary) must be set to host name as the host name.

Each server parameter (primary and secondary) can be followed by one or more of the following parameters that further define the transfer set-up: port, user, pwd, codepage, file or xfile, key, verserial, and verhost. Each of these parameters applies to the server parameter (primary or secondary) that it immediately follows.

  • port specifies the port that the broker is accepting requests on to start a UDM server.
  • user specifies the user (local to the host on which the server will be running) under which the transfer operation is being carried out
  • pwd is the password for the user.

Note

The user and pwd parameters are not required for the local side (primary server) of a two-party transfer, as the UDM Manager will be running as the user that invoked it.

  • codepage specifies the codepage that will be used for text translation of transferred data. In addition to codepage (.utt) files supplied by the Universal Agent install, UDM supports codepage values of UTF-8, UTF-16, UTF-16BE (except on AIX), and UTF-16LE.

    When specified as the source codepage of a file transfer, the UTF-16 encodings describe the type of encoding - little endian or big endian - the conversion routines can expect to encounter in the input file. When a codepage of UTF-16 is specified the conversion routines will rely on the input file's byte order mark (BOM) or - if no BOM is present - the default encoding of the system on which the input file resides. When a codepage of UTF-16BE or UTF-16LE is specified, the conversion routines expect the input file to be encoded as big endian or little endian, respectively, regardless of what the file's actual encoding is.

    When specified as the target codepage of a file transfer, the UTF-16 encodings specify the encoding - little endian or big endian - the output file receives. When a codepage of UTF-16 is specified, the output file receives the default encoding of the system upon which it is written. When a codepage of UTF-16BE or UTF-16LE is specified, the output file is encoded as big endian or little endian, respectively, regardless of the system's native encoding.

Note

For AIX, a codepage value of UTF-16BE is not supported, but a codepage value of UTF-16 will create a big-endian encoded file. UTF-16LE is supported on AIX to create a little endian-encoded file.

Note

Use the bom attribute together with one of the UTF-16 encodings to control whether or not a byte order mark (BOM) is included in the output file.

  • file or xfile parameter specifies a file (plain text or Universal Encrypted text, respectively) that contain *port*, *user*, *pwd*, and/or *codepage* in the format of a UDM command file (see [#file / xfile Parameters Format]). If file or xfileis specified, its values apply to the server (primary or secondary) preceding it in the command. These file or xfilevalues override any values specified by the port, user, pwd, and /or codepage parameters following that server.
  • key specifies the encryption key used to decrypt the encrypted file specified by xfile.
  • verserial specifies either:
    • <serial number>
      • For a Two-Party Transfer Session: The secondary verserial <serial number> is verified by the UDM Manager (the primary server) against the serial number contained in the secondary UDM Server's Universal Broker X.509 certificate.
      • For a Three-Party Transfer Session: The primary verserial <serial number> is verified by the UDM Manager against the serial number contained in the primary UDM Server's Universal Broker X.509 certificate. The secondary verserial <serial number> is verified by the primary UDM Server against the serial number contained in the secondary UDM Server's Universal Broker X.509 certificate.
    • no
      • For a Two-Party Transfer Session: UDM Manager (the primary server) will not verify the serial number of the UDM Server (the secondary server).
      • For a Three-Party Transfer Session: If the primary verserial is no, the UDM Manager will not verify the serial number of the primary UDM Server. If the secondary verserial is no, the primary UDM Server will not verify the serial number of the secondary UDM Server.
  • verhost specifies either:
    • yes
      • For a Two-Party Transfer Session: The secondary verhost <host name> is verified by the UDM Manager (the primary server) against the host name contained in the secondary UDM Server's Universal Broker X.509 certificate.
      • For a Three-Party Transfer Session: The primary verhost <host name> is verified by the UDM Manager against the host names contained in the primary UDM Server's Universal Broker X.509 certificate. The secondary verhost <host name> is verified by the primary UDM Server against the host names contained in the secondary UDM Server's Universal Broker X.509 certificate.
    • no
      • For a Two-Party Transfer Session: UDM Manager (the primary server) will not verify the host name of the UDM Server (the secondary server).
      • For a Three-Party Transfer Session: If the primary verhost is no, the UDM Manager will not verify the host name of the primary UDM Server. If the secondary verhost is no, the primary UDM Server will not verify the host name of the secondary UDM Server.
    • <host name>
      • For a Two-Party Transfer Session: The secondary verhost <host name> is verified by the UDM Manager (the primary server) against the host names contained in the secondary UDM Server's Universal Broker X.509 certificate.
      • For a Three-Party Transfer Session: The primary verhost <host name> is verified by the UDM Manager against the host names contained in the primary UDM Server's Universal Broker X.509 certificate. The secondary verhost cannot use <host name>.

The encrypt parameter specifies either:

  • yes
    An agreed-upon cipher will be negotiated based on the components data_ssl_cipher_list configuration value.
  • no
    NULL-MD5 is used as the encryption method.
    • cipher
      Specific cipher to use as encryption method: AES256-GCM-SHA384,AES256-SHA,AES128-GCM-SHA256,AES128-SHA,ECDHE-RSA-AES256-GCM-SHA384,ECDHE-ECDSA-AES256-GCM-SHA384,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-ECDSA-AES128-GCM-SHA256,RC4-SHA,RC4-MD5,DES-CBC3-SHA,NULL-SHA,NULL-SHA256,NULL-MD5. Specifying NULL-NULL as the cipher completely disables SSL/TLS when NULL-NULL also is specified in the UDM Server Data Cipher Lists associated with a transfer.

Note

If encrypt is not specified, the value specified by the UDM Manager DATA_SSL_CIPHER_LIST configuration option is used (default is no).

The compress parameter can have either of the following values:

  • yes
    Compression option in the UDM Manager's configuration file is used.
  • no
    No compression is required when transferring data. However, compression will be used if the UDM Server DATA_COMPRESSION configuration option is set to yes.
  • force
    No compression is used when transferring data, even if the UDM Server DATA_COMPRESSION option is set to yes.
  • zlib
    Forces the transfer servers to use ZLIB compression when transferring files.
  • hasp
    Forces the transfer servers to use HASP compression.

If compress is not specified, a default value of no is used.
 

The nft parameter specifies whether or not the UDM sessions will be network fault tolerant.
 

The comment parameter specifies a comment for a single session (or overrides a comment specified by the COMMENT option.)

For example: open src=* dst=zos14 comment="Data transfer for account 94882"
 

The tt parameter specifies where codepage translation is performed for files transferred in text mode, thus allowing you to choose which side of the connection will incur the overhead of codepage translation

The tt parameter can have either of the following values:

  • direct specifies that codepage translation will be performed in the component sending the file - prior to transmission.
  • deferred specifies that codepage translation will be performed in the component receiving the file - after transmission.

If tt is not specified, the translation defaults to direct.


The minsslprotocol parameter specifies the minimum SSL/TLS protocol to be used in both control and data sessions between client and server parties.

The minsslprotocol parameter can have either of the following values:

  • tls1_0 specifies that the minimum SSL/TLS protocol is TLS 1.0.
  • tls1_2 specifies that the minimum SSL/TLS protocol is TLS 1.2.
  • tls1_3 specifies that the minimum SSL/TLS protocol is TLS 1.3.

    TLS 1.3 is NOT currently supported on HP-UX and z/OS

Parameters

Parameter

Values

Description

primary







[{*|local|host name}]







Logical name of the primary transfer server.

If the value is * or local, a two-party transfer is initiated, with the UDM Manager acting as the primary server.

If only one server is specified. it is assumed to be the secondary. In this case, primary is assumed to be local and a two-party transfer is implied.

If both primary and secondary servers are specified, and the value of primary is host name, a three-party transfer is initiated with the primary server running on the machine specified by host name. The IP address of the primary server can also be used for host name.

secondary

host name

Logical name of the secondary server. Its value is the host name or IP address of the machine on which the secondary server will be running.

The host name of the secondary server must be given from the perspective of the primary transfer server, not the UDM Manager.

port *

TCP port number or service name

Port on which the Broker that will initiate the transfer server is listening. If the port parameter is not specified, the port number is assumed to be 7887.

The port parameter is not valid for the primary server in a two-party transfer.

user *

Valid username on the system the transfer server will be running on.

User name to authenticate with on the transfer server.

The user name must be valid on the system. Once authenticated, the default directory on the transfer server is set to the user's home directory under UNIX and HFS. Under Windows, the default directory will be a directory created for the user underneath where the Universal Agent suite is installed. For z/OS under the dsn file system, the user name will be the high level qualifier.

This parameter is not valid for the primary server in a two-party transfer.

pwd *

Password of the user to authenticate.

Password, for the specified user name, for authenticating the user on the transfer server.

This parameter is not valid for the primary server in a two-party transfer.

codepage *

Valid codepage

Codepage used for text translation on the transfer server.

UTF-8, UTF-16, UTF-16BE (except on AIX), and UTF-16LE are supported for text translation. However, they are not a supported value for the UDM Manager CODE_PAGE or UDM Server CODE_PAGE configuration options.

If no codepage is specified, the codepage listed in UDM's configuration will be used.

file *

Valid filename

Plain text file containing the values for the transfer server: port, user, pwd, and/or codepage (see #file / xfile Parameters Format, below).

These values override any values specified by the port, user, pwd, and /or codepage parameters for the specified transfer server.

xfile *

Valid filename

Universal Encrypted text file containing the values for the transfer server: port, user, pwd, and/or codepage (see #file / xfile Parameters Format, below).

These values override any values specified by the port, user, pwd, and /or codepage parameters for the specified transfer server.

key *

Key used to decrypt the file specified by xfile

Key used to decrypt the file specified by the xfile parameter. If the key parameter is not specified, the default key for Universal Encrypt is used.

verserial *

<serial number> or no

Specification for authenticating the UDM Server serial number.

  • <serial number> specifies:
    • For a Two-Party Transfer Session: The secondaryverserial <serial number> is verified by the UDM Manager (the primary server) against the serial number contained in the secondary UDM Server's Universal Broker X.509 certificate.
    • For a Three-Party Transfer Session: The primary verserial<serial number> is verified by the UDM Manager against the serial number contained in the primary UDM Server's Universal Broker X.509 certificate. The secondaryverserial <serial number> is verified by the primary UDM Server against the serial number contained in the secondary UDM Server's Universal Broker X.509 certificate.
  • no specifies:
    • For a Two-Party Transfer Session: UDM Manager (the primary server) will not verify the serial number of the UDM Server (the secondary server).
    • For a Three-Party Transfer Session: If the primaryverserial is no, the UDM Manager will not verify the serial number of the primary UDM Server. If the secondaryverserial is no, the primary UDM Server will not verify the serial number of the secondary UDM Server.

verhost *

yes, no, or <host name>

Specification for authenticating the UDM Server host name.

  • yes specifies:
    • For a Two-Party Transfer Session: The secondary verhost<host name> is verified by the UDM Manager (the primary server) against the host name contained in the secondary UDM Server's Universal Broker X.509 certificate.
    • For a Three-Party Transfer Session: The primary verhost<host name> is verified by the UDM Manager against the host names contained in the primary UDM Server's Universal Broker X.509 certificate. The secondary verhost<host name> is verified by the primary UDM Server against the host names contained in the secondary UDM Server's Universal Broker X.509 certificate.
  • no specifies:
    • For a Two-Party Transfer Session: UDM Manager (the primary server) will not verify the host name of the UDM Server (the secondary server).
    • For a Three-Party Transfer Session: If the primary verhostis no, the UDM Manager will not verify the host name of the primary UDM Server. If the secondary verhost is no, the primary UDM Server will not verify the host name of the secondary UDM Server.
  • <host name> specifies:
    • For a Two-Party Transfer Session: The secondary verhost<host name> is verified by the UDM Manager (the primary server) against the host names contained in the secondary UDM Server's Universal Broker X.509 certificate.
    • For a Three-Party Transfer Session: The primary verhost<host name> is verified by the UDM Manager against the host names contained in the primary UDM Server's Universal Broker X.509 certificate. The secondary verhostcannot use <host-name>.

encrypt

yes, no, or cipher

Encryption method for the transfer session.

  • If the value is yes, an agreed-upon cipher will be negotiated based on the components data_ssl_cipher_list configuration value.
  • If the value is no, the NULL-MD5 cipher is used.

Otherwise, a valid cipher must be specified:

AES256-GCM-SHA384,AES256-SHA,AES128-GCM-SHA256,AES128-SHA,ECDHE-RSA-AES256-GCM-SHA384,ECDHE-ECDSA-AES256-GCM-SHA384,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-ECDSA-AES128-GCM-SHA256,RC4-SHA,RC4-MD5,DES-CBC3-SHA,NULL-SHA,NULL-SHA256,NULL-MD5. Specifying NULL-NULL as the cipher completely disables SSL/TLS when NULL-NULL also is specified in the UDM Server Data Cipher Lists associated with a transfer.

compress

yes, no, force, hasp, or zlib

Compression method for the transfer session:

  • If the value is yes, the compression method specified in the UDM Manager's configuration is used.
  • If the value is no, no compression is required; however, compression will be used if the UDM Server DATA_COMPRESSION configuration option is set to yes.
  • If the value is force, no compression is used, even if the UDM Server DATA_COMPRESSION option is set to yes. .
  • If the value is hasp, HASP compression is used.
  • If the value is zlib, ZLIB (ZIP) compression is used.

nft

yes or no

Specification for whether or not the session is network fault tolerant:

  • yes specifies that the session will be network fault tolerant.
  • no specifies the session will not be network fault tolerant.

comment

text

Comment for a single session (or overrides a comment specified by the COMMENT option).
 
For example: open src=* dst=zos14 comment="Data transfer foraccount 94882"

tt

direct or deferred

Specification for where codepage translation is performed for files transferred in text mode, thus allowing you to choose which side of the connection will incur the overhead of codepage translation:

  • direct specifies that codepage translation will be performed in the component sending the file - prior to transmission.
  • deferred specifies that codepage translation will be performed in the component receiving the file - after transmission.

If the tt parameter is not specified, the translation defaults to direct.


minsslprotocol

tls1_0 or tls1_2 or tls1_3

Minimum SSL/TLS protocol to be used in both control and data sessions between client and server parties.

  • tls1_0 specifies that the minimum SSL/TLS protocol is TLS 1.0.
  • tls1_2 specifies that the minimum SSL/TLS protocol is TLS 1.2.
  • tls1_3 specifies that the minimum SSL/TLS protocol is TLS 1.3.

    TLS 1.3 is NOT currently supported on HP-UX and z/OS

Examples

To open a two-party transfer session between two machines, explicitly specifying the primary server:

open primary=* secondary=mvsmachine


To open a two-party transfer session between two machines, not specifying the primary server:

open secondary=mvsmachine


To open a three-party transfer session between two machines:

open primary=ntmachine secondary=mvsmachine


To open a three-party transfer session between two machines with the primary server's options coming from an encrypted configuration file and the secondary server having an authenticate user and changing the codepage for its side of the transfer:

open primary=ntmachine xfile=enc.dat dst=test.bak user=me pwd=mypwd
     codepage=IBM277


To open a three-party transfer session between two machines and verify the name and serial number between the UDM Manager and the primary server's Universal Broker X.509 certificate, as well as between the primary server and the secondary server's Universal Broker X.509 certificate:

open primary=abc port=7887 user=user1 pwd=pwd11 verhost=yes verserial=1234 +
      secondary=def port=7887 user=user2 pwd=pwd2 verhost=yes verserial=5678


To open a two-party transfer session between two machines and verify the host name and serial number of the UDM server's Universal Broker X.509 certificate:

open dst=l64agent port=7887 user=user1 pwd=pwd1 verhost=yes verserial=1234

OR

open src=* port=7887 +
      dst=l64agent port=7887 user=user1 pwd=pwd1 verhost=yes verserial=1234

file / xfile Parameters Format

The parameters in a file or xfile are in the same format as the parameters in a UDM command file, as shown in the following table.

Note

file and xfile can be shared with Universal Command.

open Command Parameter Format

file / xfile Parameter Format

Description

port=broker-port

-port broker-port

Port that the broker is accepting requests on to start a UDM server.

user=user-name

-userid user-name

User (local to the host on which the server will be running) under which the transfer operation is being carried out.

pwd=password

-pwd password

Password for the user.

codepage=codepage

-codepage codepage

Codepage that will be used for text translation of transferred data.