CONFIG SOCKET Command   

Use the CONFIG SOCKET command to add, change, or delete TCP sockets that VM:Webgateway can use for incoming TCP/IP connections.

When configuring a TCP socket, you must associate the socket with a server root domain. The server root domain is the location you want to serve the files—a minidisk, SFS directory, BFS directory, or using CMS search order when serving files from minidisks and SFS directories accessed by the VM:Webgateway SVM.

In addition, you can optionally specify a contact name and e-mail address that VM:Webgateway will display on configuration forms and in certain communications to users. Examples of such communications are:

• Messages stating the product's configuration was successfully updated.
• Output generated by a CGI programmer.
• Error documents that VM:Webgateway serves when it encounters problems serving files from the server root domain. VM:Webgateway uses the e-mail address to include a mailto: URL. With the contact information in an error document, the web browser user who receives the error document can report the problem to someone who can fix it.

In addition, if VM:Webgateway is using SSL Feature, you can also indicate that you want to use SSL when serving files from this TCP socket. When you use SSL, you provide the following information as well:

• Server certificate or certificate chain that attests to the identity of your organization
• Optionally, cipher suites you do not want VM:Webgateway to use
• Optionally, client CA certificates that VM:Webgateway can use to validate the client certificates of web browser users. After a client certificate is validated, VM:Webgateway can use it to authenticate and authorize the user.

When you initially install VM:Webgateway, it has one TCP socket with the following settings:

You can define multiple TCP sockets. The TCP sockets do not have to specify the same IP address. Using more than one IP address for your site is called virtual hosting.

Syntax

To identify a TCP socket and define its server root domain as a minidisk:

 CONFIG SOCKET ADD ipaddress tcp-portnumber ... 
    ... ROOT MDISK userid vaddr ... 
    ... [ ( [CONTACTNAME [NONE | /name/]] ... 
    ...     [CONTACTEMAIL [NONE | e-address]] ... 
    ...     [NOSSL | SSL parameters] ] 

To identify a TCP socket and define its server root domain as an SFS directory:

 CONFIG SOCKET ADD ipaddress tcp-portnumber ...
    ... ROOT SFS sfsdir ... 
    ... [ ( [CONTACTNAME [NONE | /name/]] ... 
    ...     [CONTACTEMAIL [NONE | e-address]] ... 
    ...     [NOSSL | SSL parameters] ] 

To identify a TCP socket and define its server root domain as a BFS directory:

 CONFIG SOCKET ADD ipaddress tcp-portnumber ...
    ... ROOT BFS bfsdir ... 
    ... [ ( [CONTACTNAME [NONE | /name/]] ... 
    ...     [CONTACTEMAIL [NONE | e-address]] ... 
    ...     [NOSSL | SSL parameters] ] 

To identify a TCP socket and define its server root domain to use CMS search order:

 CONFIG SOCKET ADD ipaddress tcp-portnumber ...
    ... ROOT CMS filename ... 
    ... [ ( [CONTACTNAME [NONE | /name/]] ... 
    ...     [CONTACTEMAIL [NONE | e-address]] ... 
    ...     [NOSSL | SSL parameters] ] 

To change a TCP socket's characteristics:

 CONFIG SOCKET REPLACE ipaddress tcp-portnumber ...
    ... ROOT {MDISK userid vaddr | SFS sfsdir | ...
    ... BFS bfsdir | CMS filename} ...
    ... [ ( [CONTACTNAME [NONE | /name/]] ... 
    ...     [CONTACTEMAIL [NONE | e-address]] ... 
    ...     [NOSSL | SSL parameters] ] 

To delete a TCP socket:

 CONFIG SOCKET DELETE ipaddress tcp-portnumber 

parameters:

 CERTIFICATE (server [ca(1) ca(2) ... ca(n)]) ...
    ... [EXEMPT SSLV3 ( {RSA_EXPORT/RC4_40/MD5 | ...
    ...  RSA_EXPORT/RC2_40/MD5} )]...
    ... [CLIENTCACERTIFICATES (cca-cert(1) ...
    ...  cca-cert(2)...cca-cert(n))] 

Parameters/Options

[ADD | DELETE | REPLACE]

Specifies that you are identifying, changing, or deleting the TCP socket identified by the ipaddress and tcp-portnumber parameters.

Use the REPLACE parameter to change the location of the server root domain or use of SSL for a specified TCP socket. For example, if a TCP socket currently uses a minidisk for its server root domain, you can change the TCP socket to use an SFS directory.

You cannot use the REPLACE parameter to change the IP address or port number that identifies a TCP socket. To change an IP address or port number for a TCP socket, you must delete the TCP socket, and then identify a new TCP socket with the IP address, port number, server root domain, and SSL information you want.

ipaddress

IP address VM:Webgateway is to use for incoming connections. You can specify an IP address in either of two ways:

• Use an asterisk (*) to indicate that VM:Webgateway is to accept connections for all IP addresses that the VM TCP/IP server is hosting.

• Use dotted decimal form to identify a specific IP address.

An asterisk is the default value.

tcp-portnumber

TCP port VM:Webgateway is to use for incoming connections. The HTTP default port when a web server is not using SSL is 80; the HTTP default when SSL is in use is port 443. You can specify any number from 1 through 65534; however, use caution when you specify a port number other than 80 or 443. Web browsers and other applications expect port numbers to follow industry conventions for port numbers and protocols. These conventions restrict which protocols can use which port numbers. (For example, port 25 is reserved for SMTP mail.) If you specify a port number that is used by another protocol, other applications might try to connect with the VM:Webgateway port expecting a different protocol and then experience problems. If you must use a port other than 80 or 443, select one that has not been set aside for a particular protocol. The following URL contains information about the conventions for port use:

http://ds.internic.net:80/rfc/rfc1700.txt

ROOT

A required keyword that indicates that the following parameters specify the server root domain location. Specify this parameter immediately before the MDISK, SFS, BFS, or CMS parameter.

MDISK userid vaddr

Minidisk that is the server root domain. You cannot use pattern matching in userid or vaddr.

When serving files from a minidisk, identify all the files you want to serve in DIRMAP files. All DIRMAP files and the files you want to serve must reside on this minidisk. The VM:Webgateway service virtual machine must have read access to this minidisk.

SFS sfsdir

SFS directory that is the server root domain. Specify the fully qualified directory name. You cannot use pattern matching in sfsdir.

When serving files from an SFS directory, all files you want to serve must reside in the directory, and, optionally, its subdirectories. The VM:Webgateway service virtual machine must have authorization to read the files you want to serve.

BFS bfsdir

BFS directory that is the server root domain. Specify the fully qualified directory name. You must exactly match the character case for the BFS directory name when specifying bfsdir. You cannot use pattern matching.

When serving files from a BFS directory, all files you want to serve must reside in this directory, and, optionally, its subdirectories. The VM:Webgateway service virtual machine must have permission to read and search the directory and the subdirectories to find the files you want to serve. In addition, VM:Webgateway requires read permission to each static file you want to serve and read and execute permission to each CGI program you want to serve.

CMS filename

Filename of the first DIRMAP file VM:Webgateway should use to identify the files to serve.

When serving files using CMS search order, you must identify all the files you want to serve in DIRMAP files. All DIRMAP files and the files you want to serve must reside on minidisks or SFS directories accessed by the VM:Webgateway service virtual machine. If more than one version of a DIRMAP file exists, VM:Webgateway uses the first version it finds using the CMS search order. For example, if the ROOT DIRMAP file resides on both the J-disk and the K-disk, VM:Webgateway uses the version from the J-disk. Similarly, if more than one version of a file you want to serve exists, VM:Webgateway serves the first version it finds using the CMS search order. Therefore, ensure that the files you want VM:Webgateway to use are in the proper search order.

---

Note: The virtual addresses of the accessed minidisks from which you want to serve files must be in the ranges 0100-01FF or 0800-1FFF. VM:Webgateway reserves virtual addresses outside these ranges for internal use. At initialization, VM:Webgateway detaches minidisks that have virtual addresses outside the ranges 0100-01FF or 0800-1FFF.

---

CONTACTNAME [NONE | /name/]

Use the CONTACTNAME option to specify a contact name that VM:Webgateway will display on configuration forms and in certain communications to users. Examples of such communications are presented at the beginning of this page.

If you want to display the contact name, identify it with the name parameter. The value you specify must be preceded and followed by a delimiting character (for example, /Mark/ or "Mark Smith"). If you specify the name parameter, one of several messages will display:

• If you also specify an e-mail address (CONTACTEMAIL option), the message reads, "Send comments or questions to name," where name is hyperlinked to the mailto: URL. The e-mail is automatically addressed to the contact's e-mail address.
• If you do not specify an e-mail address (CONTACTEMAIL option), the message reads, "Send comments or questions to name." There is no hyperlink to the mailto: URL.

Specify NONE if you do not want to display a contact name on configuration forms or in communications to users. NONE is the default.

The CONTACTNAME option is usually used in conjunction with the CONTACTEMAIL option.

CONTACTEMAIL [NONE | e-address]

Use the CONTACTEMAIL option to specify a contact e-mail address that VM:Webgateway will display on configuration forms and in certain communications to users. Examples of such communications are presented at the beginning of this page.

If you want to display the contact e-mail address, identify it with the e-address parameter (for example, Mark_Smith@bigcorp.com). If you specify the e-address parameter, one of several messages will display:

• If you also specify a contact name (CONTACTNAME option), the message reads, "Send comments or questions to name," where name is hyperlinked to the mailto: URL. The e-mail is automatically addressed to e-address.
• If you do not specify a contact name (CONTACTNAME option), the message reads, "Send comments or questions to e-address," where e-address is hyperlinked to the mailto: URL.

---

Note: By default, the logical character-delete symbol for a virtual machine is the at sign (@). As a result, when you use the at sign in a contact e-mail address, CMS deletes the at sign and the preceding character. There are several ways to avoid this problem.

• One is to enter the TERMINAL CHARDEL OFF command before entering the CONFIG SOCKET command. (You must then enter the TERMINAL CHARDEL ON command after using the CONFIG SOCKET command.) For more information about these commands, refer to IBM documentation.
• Another way is to place a double-quote character (or whatever the escape character is at your site) just before the at sign so the at sign is taken literally (for example, Fred"@company.com).

---

You can read more about the mailto: URL scheme at http://info.internet.isi.edu:80/in-notes/rfc/files/rfc2368.txt. You can read more about forming the e-mail address portion of the mailto: tag at http://info.internet.isi.edu:80/in-notes/rfc/files/rfc822.txt.

Specify NONE if you do not want to display a contact e-mail address on configuration forms or in communications to users. NONE is the default.

The CONTACTEMAIL option is usually used in conjunction with the CONTACTNAME option.

NOSSL

Indicates you do not want VM:Webgateway to use SSL. This is the default.

When you specify NOSSL, web browser users must specify http:// as the first part of URLs to request information served using the TCP socket.

HTTP uses TCP port 80 by default when SSL is not in use. If you specify NOSSL and do not specify TCP port 80, web browser users have to specify the TCP port in URLs. The following shows a URL for a server that is not using SSL and for which the TCP port is 980:

http://www.company.com:980/

SSL parameters

Indicates that you want VM:Webgateway to use SSL.

To use SSL, you must have a VM:Webgateway CPUID that allows you to use SSL Feature and the OPTIONS SSL and KEYPASS records in the VMWEBSRV CONFIG file. The parameters that are associated with SSL are the CERTIFICATE, EXEMPT, and CLIENTCACERTIFICATES parameters described below.

When you specify SSL, web browser users must specify https:// as the first part of URLs to request information served using the TCP socket.

HTTP uses TCP port 443 by default when SSL is in use. If you specify SSL and do not specify TCP port 443, web browser users will have to specify the TCP port in URLs. The following shows a URL for a server that is using SSL and for which the TCP port is 943:

https://www.company.com:943/

CERTIFICATE (server [ca(1) ca(2) ... ca(n)])

Name of the server certificate or names of the certificates in a certificate chain that attest to the identity of your organization.

A certificate chain consists of a server certificate and one or more CA certificates. If you are using a certificate chain, specify the certificates in the order they were returned by the certificate authority starting with the server certificate.

When a web browser requests data from your server, VM:Webgateway sends the server certificate or certificate chain to the web browser. If you specify the SSL parameter, you must identify either a server certificate or certificate chain.

[EXEMPT SSLV3 ( {RSA_EXPORT/RC4_40/MD5 | ...
   ... RSA_EXPORT/RC2_40/MD5} )]

Cipher suites you do not want VM:Webgateway to use.

Each version of SSL supports a set of cipher suites. To remove cipher suites, identify the version of SSL followed by a list of cipher suites that are associated with that version of SSL that you do not want VM:Webgateway to use. VM:Webgateway supports only SSL version 3. VM:Webgateway identifies cipher suites using the format exchange/encryption/hashing.

Exempt a cipher suite if you learn that it has been compromised and, as a result, you believe that using the cipher suite compromises your site security. If you want to force VM:Webgateway to use a particular cipher suite, remove all cipher suites except the one you want to use.

Note: Do not exempt all cipher suites; VM:Webgateway requires at least one cipher suite that the web browser also supports.

[(CLIENTCACERTIFICATES (cca-cert(1) cca-cert(2) ...
    ... cca-cert(n) )]

Names of the client CA certificates VM:Webgateway uses to validate the client certificates of web browser users being served through this TCP socket. If you want to use client certificates to authenticate web browser users on a particular TCP socket, you must specify one or more client CA certificates for that socket.

---

Examples

• You want to serve files from minidisks and SFS directories that are accessed by the VM:Webgateway service virtual machine. You want to serve data without using SSL. When determining what files to serve, you want VM:Webgateway to first look in the ROOTDMN DIRMAP file. Enter the following command from the VM:Webgateway service virtual machine:

  config socket add * 80 root cms rootdmn (nossl

• Use the previous example as a starting point. In addition, you want error documents to automatically contain the message Send comments or questions to Mark Smith. You also want Mark Smith hyperlinked to the VM:Webgateway mailto: URL capability so web browser users can click on the name and easily generate an e-mail message to Mark Smith. Enter the following command from the VM:Webgateway service virtual machine:

  config socket add * 80 root cms rootdmn (contactname /Mark Smith/ contactemail mark_smith"@bigcorp.com nossl

  Note the use of the escape character before the at sign in the e-mail address.

• You want to use SSL. You want to set the TCP port to 443, and the server root domain to SFS directory VMSYSU:WEBSERVER.SERVERROOT. You want to use server certificate SVRCERT, and client CA certificates CCACERT1, CCACERT2, and CCACERT3. You want to use all available cipher suites. Enter this command from a VM userid with VM:Webgateway SYSADMIN authorization:

  vmwebsrv config socket add * 443 root sfs vmsysu:webserver.serverroot ( ssl certificate (svrcert) clientcacertificates (ccacert1 ccacert2 ccacert3)

  In this example, because SSL is in use and the TCP port is 443, web browser users do not have to specify the TCP port in URLs. The following shows a URL for a server that is using SSL and for which the TCP port is 443:

  https://www.company.com/

• You want to use SSL. You want to set the TCP port to 943 and the server root domain to the SFS directory VMSYSU:WEBSERVER.SERVERROOT. You want to use the certificate chain that contains the server certificate SVRCERT and CA certificate INTCERT. You want to exempt the cipher suite RSA-EXPORT/RC2_40/MD5 to force VM:Webgateway to use RSA-EXPORT/RC4_40/MD5. Enter this command from the VM:Webgateway service virtual machine:

  config socket add * 943 root sfs vmsysu:webserver.serverroot ( ssl certificate (svrcert intcert) exempt sslv3 (rsa-export/rc2_40/md5)

  In this example, because SSL is in use and the TCP port is 943, web browser users must specify the TCP port in URLs. The following shows a URL for a server that is using SSL and for which the TCP port is 943:

  https://www.company.com:943/

• To delete the TCP socket defined at IP address 10.244.83.43 and TCP port 80, enter this command from the VM:Webgateway service virtual machine:

  config socket delete 10.244.83.43  80

• The TCP socket at IP address 10.244.83.43 and TCP port 80 was defined to use an SFS directory as its server root domain. You want to redefine the TCP socket to use the minidisk VMWEBSRV 1C0 as its server root domain. Enter this command from the VM:Webgateway service virtual machine:

  config socket replace 10.244.83.43  80 root mdisk vmwebsrv 1c0

• To change the TCP port from the default of 80 to 983, but keep the server root domain as the BFS directory /../VMBFS:VMSYSU:VMWEBSRV/web_root, enter these commands from a VM userid with VM:Webgateway SYSADMIN authorization:

  vmwebsrv config socket add * 983 root bfs /../VMBFS:VMSYSU.VMWEBSRV/web_root ( nossl

  vmwebsrv config socket delete * 80

  In this example, because SSL is not in use and the TCP port is not 80, web browser users would have to specify the TCP port in URLs. The following shows a URL for a server root domain that is not using SSL and for which the TCP port is 983:

  http://www.company.com:983/