From m204wiki
Jump to navigation Jump to search

NEWSESCMD 'xxx' — Commands to execute on new session initiation

NEWSESCMD is a parameter on JANUS DEFINE, which defines and sets characteristics of a Janus port.

This parameter specifies the Model 204 commands to be executed when a new login session is initiated. For SRVSOCK ports every connection starts a new login session. For WEBSERV ports, a new login session is only started when the user requests a "login required" URL (based on JANUS WEB ALLOW rules) and the user is not continuing a login session via SSLSES or SESCOOKIE.

Multiple commands must be separated by AND, and any command that contains blanks must be enclosed in quotes. NEWSESCMD may span more than one line (if a hyphen (-) continues the line), but the total length of commands plus one overhead byte per command cannot exceed 255 bytes.

The NEWSESCMD commands are executed before any commands specified in the CMD clause or JANUS WEB ON rules for WEBSERV ports. User authentication is the primary function of NEWSESCMD commands. Any $Web_ function can be issued in NEWSESCMD commands on WEBSERV ports, and any $Sock_ function can be issued in NEWSESCMD commands on SRVSOCK ports. In addition, a NEWSESCMD command can issue the $Sir_Login function as well as the $Web_Password function on WEBSERV threads. The $Web_Hdr_Parm and $Web_Hdr_Parm_Lstr functions can retrieve the Authorization header parameters while running as part of a NEWSESCMD, but will otherwise return a null string.

If NEWSESCMD specifies an INCLUDE command, the included procedure is assumed to come from the first file or group specified in a NEWSESOPEN clause.

Examples of some valid NEWSESCMD clauses:


Because of the role of NEWSESCMD in enforcing user access security, most resources used during NEWSESCMD processing are automatically cleaned up after the NEWSESCMD processing is completed. This includes all files being closed and all user tables being cleared (though not resized). The one exception to this is that GTBL can be left intact after NEWSESCMD processing, if the NEWSESNOCLEARG parameter is specified on the port definition.

If a NEWSESCMD command logs a user in using $Sir_Login, the rest of the request runs under that userid. For web requests, it is possible that a NEWSESCMD will log a user on, but that user will not be authorized to run the request URL based on JANUS WEB ALLOW rules. In such a case, Janus Web Server will either send a "404 Unauthorized" status to the browser (which will result in a login pop-up window being presented to the end-user), or it will run the UNAUTHORIZED exception handler, if one is present.

If the NEWSESCMD does not perform a $Sir_Login, processing continues as it would without a NEWSESCMD. That is, on a SRVSOCK port, the request will run under the SOCKUSER userid, and on a WEBSERV port, Janus Web Server will attempt to log the user in based on the userid and password passed in the HTTP authorization header, if one is present.

NEWSESCMD command processing can also close the connection with the client, either with a $Sock_Close on a SRVSOCK port or with a $Web_Done on a WEBSERV port. In such a case, no further processing occurs on the thread after the NEWSESCMD commands complete.

This parameter is valid for SRVSOCK, WEBSERV, and TNSERV port types.

This parameter is not valid on an FTPSERVER port definition.

For TNSERV ports, the NEWSESCMD is only run for the initial connection. If a user logs off and logs back on in the same connection, the NEWSESCMD will not be executed. Because of this, if a NEWSESCMD does a $Sir_Login, it might make sense for it to specify the TRUST parameter on the $Sir_Login to allow subsequent logins in the same connection to be trusted logins.

See also