JANUS CLSOCK

Defines rules for a Janus socket client

The JANUS CLSOCK command defines the rules for a Janus Sockets client CLSOCK or DEBUGGERCLIENT port. These rules control access to the port. System administrators always have access to a client port, so no CLSOCK rules are required to provide socket access to these users.

The JANUS CLSOCK command is slightly different from most Janus commands in that it usually takes a set of commands to fully specify the rules for a port. For instance, it may take a number of commands to specify the various users and applications that may use a port on the socket-connection $function $Sock_Conn or Socket class method New.

The order in which JANUS CLSOCK commands are specified also affects how they are processed.

Syntax

JANUS CLSOCK portname rule_type [optional_parameters]

Where:

portname	A 1 - 30 character name of the port, or a pattern specifying a set of ports, for which the rule is being defined. Wildcards are allowed.
rule_type	The type of rule being specified for the port or ports. Valid rule_type are: DISALLOW — Removes access permission. ALLOW — Assigns access permission.
optional_parameters	These parameters vary with the rule_type value. See JANUS CLSOCK rule types, below.

Usage notes

• The ALLOW and DISALLOW rules are processed together, from most recent to oldest. The optional parameters allowed for the JANUS CLSOCK command depend on the rule_type value. The rule types are shown below, followed by a section giving examples and showing the interaction of JANUS CLSOCK commands.
• The JANUS CLSOCK and JANUS SRVSOCK commands differ from the corresponding rules available with the JANUS WEB command in the following ways:
  • JANUS WEB does not allow any optional parameters (for example, USGROUP on the DISALLOW rule).
  • The default access for WEBSERV non-SSL ports and SRVSOCK ports is ALLOW. The default access for WEBSERV SSL ports and CLSOCK and DEBUGGERCLIENT ports is DISALLOW.
  • ALLOW and DISALLOW are the only rule types for JANUS CLSOCK and JANUS SRVSOCK. There are a number of other rule types for JANUS WEB.

Examples

This is a simple port definition deck that allows connections to any remote site:

JANUS FORCE CLSOCK JANUS DELETE CLSOCK JANUS DEFINE CLSOCK * CLSOCK 5 TIMEOUT 240 REMOTE * * MASTER JANUS CLSOCK CLSOCK ALLOW REMOTE * * JANUS START CLSOCK

Here is a similar port definition deck enhanced to support SSL connections (the SSL 0 option) to any remote port for any valid user (the ALLOW rules). The ADDCA rule at the end supports connections to ports that are secured with "unrecognized" SSL certificates, typically these would be self-signed certificates created with the Rocket JANSSL application.

JANUS FORCE CLSOCK JANUS DELETE CLSOCK JANUS DEFINE CLSOCK * CLSOCK 5 TIMEOUT 240 REMOTE * * MASTER SSL 0 SSLOPT - SSLMAXCERTL 4096 SSLBSIZE 32767 JANUS CLSOCK CLSOCK ALLOW JANUS CLSOCK CLSOCK ALLOW REMOTE * * JANUS START CLSOCK JANUS ADDCA CLSOCK JANWEB LOCALLY.SIGNED.CERT

JANUS CLSOCK rule types

JANUS CLSOCK ALLOW

The JANUS CLSOCK ALLOW command indicates a combination of conditions which, if all specified, allow either of these:

• A socket-connection $function $Sock_Conn or Socket class method New invocation to access the CLSOCK ports that match pattern portname.
• A TN3270 Debugger user to access the DEBUGGERCLIENT ports that match pattern portname.

The default access for all CLSOCK and DEBUGGERCLIENT ports is to disallow all access &emdash; except system administrators can access any such port, regardless of rules (since a system administrator can always issue JANUS CLSOCK to grant access to herself).

For a non-system administrator, access to a CLSOCK or DEBUGGERCLIENT port depends on the most recent rule for that port that matches the conditions of the $Sock_Conn or New method call, or Sirius Debugger SIRIUS DEBUG ON command:

• If the conditions match all clauses on a JANUS CLSOCK ALLOW rule, access to the port is allowed.
• If the conditions match all clauses on a JANUS CLSOCK DISALLOW rule, access to the port is disallowed.
• If the conditions match neither an ALLOW nor DISALLOW rule, access to the port is disallowed.

If the JANUS CLSOCK ALLOW command is specified with no optional parameters, access to the CLSOCK or DEBUGGERCLIENT ports that match the pattern in portname is unrestricted.

Syntax

JANUS CLSOCK portname ALLOW - [NONE] | [USER userid | USGROUP usgroup] - [FILE procfile] - [PROC procname] - [SUBSYS subsysname] - [REMOTE rmt_host rmt_portnum]

The optional parameters for the JANUS CLSOCK ALLOW command are:

NONE	Indicates that no access is allowed to portname. If NONE is specified, no other optional parameters may be specified.
USER userid	Indicates that the Model 204 user ID userid may issue a $Sock_Conn or a New method call or a SIRIUS DEBUG ON command for portname. For example, if userid is HOMER, a user that logs in as HOMER will be allowed access to portname. If userid is SIMP*, a user that logs in as any user ID that begins with the string SIMP is allowed access to portname. The USER parameter cannot be specified if the USGROUP parameter is specified. USER '' (that is, USER with the null string) is not allowed, since there is always a (non-null) user ID when a request is issued. USER * is allowed, but it is meaningless: it does not change which conditions a rule matches.
USGROUP usgroup	Indicates that a Model 204 user is allowed access to portname if his or her user ID matches an entry in the user group identified by usgroup. User groups are defined with the JANUS DEFINEUSGROUP command. The USGROUP parameter cannot be specified if the USER parameter is specified.
FILE procfile	Indicates that access is allowed to portname if invoked by executing an outer procedure stored in a Model 204 file whose name matches the pattern procfile. FILE * indicates that access is allowed by any procedure except a temporary request or an instream procedure. FILE '' indicates that access is allowed only by a temporary request or an in-stream procedure.
PROC procname	Indicates that access is allowed to portname if invoked by executing an outer procedure whose name matches the pattern procname. PROC * indicates that access is allowed by any procedure except a temporary request or an in-stream procedure. PROC '' indicates that access is allowed only by a temporary request or an in-stream procedure.
SUBSYS subsysname	Indicates that a $Sock_Conn or New call or SIRIUS DEBUG ON command is allowed to access portname if issued from an APSY subsystem with a name that matches the pattern subsysname. SUBSYS * indicates that access is allowed by any subsystem. SUBSYS '' indicates that access is allowed only by a non-subsystem procedure or temporary request, or by an in-stream procedure.
REMOTE rmt_host rmt_portnum	Access is allowed to portname if the remote host and port number ($Sock_Conn or New method arguments or their defaults; or SIRIUS DEBUG ON command arguments for the Debugger Client address and port) match rmt_host and rmt_portnum, respectively. rmt_host is one of the options in the "Remote host formats" table below. rmt_portnum can be either of these: An asterisk (*), indicating access is allowed for any port number at the specified remote host. An integer in the range 1-65535, indicating that access is allowed only for the specified port number at the specified remote host. Remote host formats [NAME] hostname Access is allowed if the name of the remote host matches the pattern hostname. The null string is not allowed for hostname, since there is always a (non-null) host for the $Sock_Conn or New method or SIRIUS DEBUG ON operation. When the NAME keyword is explicitly specified, or when hostname is a form that cannot be an IP address, the clause only matches if the connection to the remote host is made using a name rather than an IP address. This leads to some subtle differences in the meaning of an asterisk in the REMOTE clause. For example, the following rule restricts the connection to any remote host at port 1234, whether the connection is specified by name or by IP address: JANUS CLSOCK FOO ALLOW REMOTE * 1234 The following clause restricts the connection to any remote host at port 1234, as long as the connection is specified by host name: JANUS CLSOCK FOO ALLOW REMOTE NAME * 1234 REMOTE * * is allowed, but it is meaningless; that is, it does not change which conditions a rule matches. REMOTE NAME * *, however, does restrict a rule to match only if the host name is specified on the connection, but it matches any remote host. IPGROUP ipgroup Access is allowed if the remote host's IP address matches one of the entries in ipgroup. IP groups are defined with the JANUS DEFINEIPGROUP command. ipaddr Access is allowed if the remote host has an IP address that matches ipaddr. ipaddr can be an IPV4 dotted-decimal address, an IPV6 address (as of version 7.7 of Model 204), or it can be a subnet. IPV4 subnets are indicated by an IP address followed by one of these: A forward slash (/) followed by a netmask (with no intervening blanks) A hyphen (-) followed by the number of bits in the subnet mask (with no intervening blanks) For example, 198.242.244.97 is a simple IP address that must be matched exactly. .198.242.244.0/255.255.255.0, which is equivalent to 198.242.244.0-24, indicates that any machine on subnet 198.242.244.0 is to be allowed access to portname. IPV6 addresses are 128-bit integers, represented with eight, colon-separated, 16-bit (four hex-digit) groups, which may be abbreviated and represented with fewer groups. For example, fe80:0000:0000:0000:0200:0000:0300:0016 or fe80::200:0:300:16. An IPV6 subnet is indicated by the first address in the range, followed by a forward slash, and a decimal value equal to the number of bits in the network prefix. A subnet that includes the example address above is: fe80::200:0/48. Note: When the IPGROUP ipgroup or the ipaddr form is used, the rule can match whether a connection is specified by host name or IP address. If the connection is by host name, it is first translated to an IP address, which is then used to match the rule.

JANUS CLSOCK DISALLOW

The JANUS CLSOCK DISALLOW command indicates a combination of conditions which, if all specified, prevent both of these:

• A socket-connection $function $Sock_Conn or object method invocation from accessing the CLSOCK ports that match pattern portname.
• A Sirius Debugger user from accessing the DEBUGGERCLIENT ports that match pattern portname.

The default access for all CLSOCK and DEBUGGERCLIENT ports is to disallow all access — except system administrators can access any CLSOCK port, regardless of rules (since a system administrator can always issue JANUS CLSOCK to grant access to herself). For a non-system administrator, access to a CLSOCK or DEBUGGERCLIENT port depends on the most recent rule for that port that matches the conditions of the $Sock_Conn or New method call, or Sirius Debugger SIRIUS DEBUG ON command:

• If the conditions match all clauses on a JANUS CLSOCK DISALLOW rule, access to the port is not allowed.
• If the conditions match all clauses on a JANUS CLSOCK ALLOW rule, access to the port is allowed.
• If the conditions match neither an ALLOW nor DISALLOW rule, access to the port is disallowed.

Syntax

JANUS CLSOCK portname DISALLOW - [USER userid | USGROUP usgroup] - [FILE procfile] - [PROC procname] - [SUBSYS subsysname] - [REMOTE rmt_host rmt_portnum]

If the JANUS CLSOCK DISALLOW command is specified with no optional parameters, no access is allowed to the CLSOCK or DEBUGGERCLIENT ports that match the pattern in portname.

The optional parameters for the JANUS CLSOCK DISALLOW command are:

USER userid	Indicates that the Model 204 user ID userid may not issue a $Sock_Conn or a New method call or a SIRIUS DEBUG ON command for portname. For example, if userid is HOMER, a user that logs in as HOMER is not allowed access to portname. If userid is SIMP*, a user that logs in as any user ID that begins with the string SIMP is not allowed access to portname. The USER parameter cannot be specified if the USGROUP parameter is specified. USER '' (that is, USER with the null string) is not allowed, since there is always a (non-null) user ID when a request is issued. USER * is allowed, but it is meaningless: it does not change which conditions a rule matches.
USGROUP usgroup	Indicates that a Model 204 user is not allowed access to portname if his or her user ID matches an entry in the user group identified by usgroup. User groups are defined with the JANUS DEFINEUSGROUP command. The USGROUP parameter cannot be specified if the USER parameter is specified.
FILE procfile	Indicates that access is not allowed to portname if invoked by executing an outer procedure stored in a Model 204 file whose name matches the pattern procfile. FILE * indicates that access is allowed by any procedure except a temporary request or an instream procedure. FILE '' indicates that access is allowed only by a temporary request or an in-stream procedure.
PROC procname	Indicates that access is not allowed to portname if invoked by executing an outer procedure whose name matches the pattern procname. PROC * indicates that access is allowed by any procedure except a temporary request or an in-stream procedure. PROC '' indicates that access is allowed only by a temporary request or an in-stream procedure.
SUBSYS subsysname	Indicates that a $Sock_Conn or New call or SIRIUS DEBUG ON command is not allowed to access portname if issued from an APSY subsystem with a name that matches the pattern subsysname. SUBSYS * indicates that access is allowed only by a non-subsystem procedure or temporary request, or by an in-stream procedure. SUBSYS '' indicates that access is allowed by any subsystem.
REMOTE rmt_host rmt_portnum	Indicates that access is not allowed to portname if the remote host and port number (from $Sock_Conn or Socket class New method arguments or their defaults; or SIRIUS DEBUG ON command arguments for the Debugger Client address and port) match rmt_host and rmt_portnum, respectively. rmt_host is one of the options in the "Remote host formats" table below. rmt_portnum is either of these: An asterisk (*), indicating access is allowed for any port number at the specified remote host. An integer in the range 1-65535, indicating that access is allowed only for the specified port number at the specified remote host. Remote host formats [NAME] hostname Access is not allowed if the name of the remote host matches the pattern hostname. The null string is not allowed for hostname, since there is always a (non-null) host for the $Sock_Conn or New method or SIRIUS DEBUG ON operation. When the NAME keyword is explicitly specified, or when hostname is a form that cannot be an IP address, the clause only matches if the connection to the remote host is made using a name rather than an IP address. This leads to some subtle differences in the meaning of an asterisk in the REMOTE clause. For example, the following rule restricts the connection to any remote host, as long as a port other than 1234 is used, whether the connection is specified by name or by IP address: JANUS CLSOCK FOO DISALLOW REMOTE * 1234 The following rule disallows a connection to any remote host at port 1234, if the connection is specified by host name. JANUS CLSOCK FOO DISALLOW REMOTE NAME * 1234 (Admittedly, these DISALLOW examples, especially the latter one, seem far-fetched and probably are not useful in practice.) REMOTE * * is allowed, but it is meaningless: it does not change which conditions a rule matches. REMOTE NAME * *, however, does restrict a rule to match only if the host name is specified on the connection, but it matches any remote host. IPGROUP ipgroup Access is not allowed if the remote host's IP address matches one of the entries in ipgroup. IP groups are defined with the JANUS DEFINEIPGROUP command. ipaddr Access is not allowed if the remote host has an IP address that matches ipaddr. ipaddr can be an IPV4 dotted-decimal address, an IPV6 address (as of version 7.7 of Model 204), or it can be a subnet. IPV4 subnets are indicated by an IP address followed by one of these: A forward slash (/) followed by a netmask (with no intervening blanks) A hyphen (-) followed by the number of bits in the subnet mask (with no intervening blanks) For example, 198.242.244.97 is a simple IP address that must be matched exactly. .198.242.244.0/255.255.255.0, which is equivalent to 198.242.244.0-24, indicates that any machine on subnet 198.242.244.0 is to be allowed access to portname. IPV6 addresses are 128-bit integers, represented with eight, colon-separated, 16-bit (four hex-digit) groups, which may be abbreviated and represented with fewer groups. For example, fe80:0000:0000:0000:0200:0000:0300:0016 or fe80::200:0:300:16. An IPV6 subnet is indicated by the first address in the range, followed by a forward slash, and a decimal value equal to the number of bits in the network prefix. A subnet that includes the example address above is: fe80::200:0/48. Note: When the IPGROUP ipgroup or the ipaddr form is used, the rule can match whether a connection is specified by host name or IP address. If the connection is by host name, it is first translated to an IP address, which is then used to match the rule.

Rule matching order and examples

Each execution of a JANUS CLSOCK subcommand adds to the set of rules for the specified port. Individual rules cannot be deleted nor modified. All rules can be deleted only by stopping and deleting the port definition. Deleting a port definition, however, should not be necessary, as long as you follow the two golden rules:

1. Specify the most general rules first and the most specific last.
2. Specify an initial rule that “clears” all related rules.

The following example illustrates these principles:

JANUS CLSOCK TEST21 DISALLOW * JANUS CLSOCK TEST21 ALLOW SUBSYS ECOMMER* JANUS CLSOCK TEST21 ALLOW PROC FILETRANS REMOTE IPADDR 169.84.111.0-24 9333 JANUS CLSOCK TEST21 ALLOW PROC FILETRANS REMOTE IPADDR 169.84.112.0-24 9333 JANUS CLSOCK TEST21 ALLOW USER SIMP*

In this example, any previously specified ALLOW rules on port TEST21 are made obsolete by the first DISALLOW rule. Once the TEST21 access rules are cleared, the rules allow invocation of $Sock_Conn or the New method for port TEST21, if any of the following conditions are met:

• It is invoked from a subsystem whose name begins with the string ECOMMER.
• It is invoked for port number 9333 at a remote host that is on either the subnet 169.84.111.0 or the subnet 169.84.112.0.
• It is invoked by a Model 204 user whose ID begins with the string SIMP.

See also

• List of Janus commands