.! CTLSMB.RNO - System manager's guide to CTLSMB Version 1.2 .! Written by Gregg Wonderly, 21-AUG-1987 .! .! RUNOFF operation instructions: .! .! $ @CTLSMB.COM .! .! to create a document for printing. .! .! We set the layout so that running page numbers are on the bottom .! .lo 1,2 .st .! .! Initial right margin - sections should never set it higher than this. .! Set page size too. .ps 57,70 .rm 65 .! .! Header level setup .sthl 6,0,0,8,9,1,1,9,2 .dhl D,D,lu,d,ll,ll .! .! .flags bold .! .c; .sk 2 .c;System Manager's Guide to CTLSMB 1.2 .title System Manager's Guide to CTLSMB 1.2 .sk 2 .c;Gregg Wonderly .c;Mathematics Department .c;Oklahoma State University .sk 1 .c;8-Dec-1987 .sk 3 .! .send toc .ifnot global .hl 1 ^&Introduction\& .send toc .endif global CTLSMB was developed by Gregg Wonderly of the Mathematics Department at Oklahoma State University. CTLSMB is a server symbiont whose intended use is to allow the VMS queuing mechanism to be used to execute programs on behalf of other users. The big difference between using CTLSMB and normal batch jobs is that the processes created by CTLSMB are cached, and therefore reusable. This makes it possible to use very periodic batch jobs with smaller overhead due to the elimination of process creation. .s CTLSMB was originally written to be used in the VMS PMDF mail project. Its purpose then (and now) was to alleviate the problem of process creation overhead due to mass batch job submission (for each mail message comming into a system, PMDF creates a batch job to deliver that mail message to its next destination. During peak times, an extremely large number of batch jobs can be started. The first few will end up delivering the mail, but all jobs must run to completion). .s It was soon discovered that CTLSMB had much wider applications, because of it's interface to the VMS queuing system. Besides PMDF, CTLSMB is currently being used to serve a generic queue that provides RJE access to an IBM mainframe. The user can issue the command "submit/queue=ibm$batch" to submit the batch job, and the command file used to process tasks for that queue takes care of packaging the file so that it can be processed. The possiblities are endless. .pg .! .hl 1 ^&Table of contents\& .req "ctlsmb.rnt" .pg .! .send toc .ifnot global .hl 1 ^&Purpose of this document\& .send toc .endif global The purpose of this document is to outline the usage of CTLSMB in such a way that the reader will be able to make use of it. As with any program that creates processes on behalf of another user, there are some security considerations. .send toc .ifnot global .hl 1 ^&Security Considerations\& .send toc .endif global Priviledges should not be taken lightly. If you create a queue and do not specify a user=xxx option in the configuration file, then processes created for that queue will be created with all priviledges, and will have the SYSTEM uic. This in itself can create problems. For this reason, queues of this nature should be adequately protected from users who should not be allowed to submit/print jobs to them. .s Applications which make use of priviledged processes must make sure to check access permissions based on the submitting user (where applicable) so that the file systems security is not compromised. E.G. Say you create a server queue that uses CTLSMB, and let it execute under the system uic. Also, let's assume that the purpose of this queue is to allow remote printing to another system. By making use of a network interface and a set of commands, you will copy files to another machine, and then issue a remote command to print the file on the remote printer. .s This is a perfectly logical application of a server symbiont, and it is possible (the symbiont can provide you the necessary restrictions). There are a few places where security can be compromised, so you must be careful. The SUBMIT and PRINT programs do not allow a user to queue a file for processing, that they do not have access to with the priviledges of their current process. This means that you do not have to check the accessability of the user and file. However, you should make sure that other devices and files used by the program running in the server queue are checked, when necessary. .! .send toc .ifnot global .hl 2 ^&Use of $CHECK__ACCESS and $CHKPRO\& .send toc .endif global The $CHECK__ACCESS and $CHKPRO system services allow you to check the access of a user to a VMS object. The $CHECK__ACCESS service is easiest to use. $CHKPRO requires many parameters to describe the access requested, and the protections on the object. For files and devices, $CHECK__ACCESS should be sufficent. If it is possible for you to use a DCL command procedure to perform the operations for the server queue, then you can use the program located in the [SRC.CHKACC] directory to check the access of users to devices and files. This program makes use of the $CHECK__ACCESS system service. See the section below that describes this program for more information on its use. .! .send toc .ifnot global .hl 1 ^&Configuration\& .send toc .endif global The configuration of CTLSMB is straight forward, however, some comments are needed to help clarify the use of some of the configuration parameters. The parameters that make the most difference in the capabilities of a process created by the symbiont, are 'user=', 'quepri=' and 'detached'. The 'user=' qualifier allows you to specify a USERNAME whose UIC will be used to create the process that will executed. IFF 'detached' is also used, the USERNAME of the created process will be the same as that specified with 'user=' (the special case of user=user means that the username is that of the submitting user). .s This is important because certain programs (like MAIL) only use the USERNAME to identify the person using the program to others. A subprocess can not have a USERNAME different than the process at the root of the tree, so the 'detached' parameter is required if you need the USERNAME to be that specified in the 'user=' parameter (otherwise it is SYSTEM, the USERNAME of the symbiont). .! .send toc .ifnot global .hl 2 ^&Non Special Configuration Parameters\& .send toc .endif global The non-special configuration parameters allow processes to be pooled. Since these parameters specify attributes that can be changed easily, the processes of queues specifying only these parameters can be shared. Any time that a queue needs a process for a task and there exists an idle process with only these attributes, then it will be used instead of the symbiont creating a new process for use by that queue. .s A process, when started, has several DCL symbol assigments passed to it via the mailbox that is associated with SYS$INPUT. The symbol names and their contents are outlined here: .s .lm +5 .LT SMB$QUEUE The Queue to which the job was SUBMIT'd or PRINT'd. SMB$EQUEUE The generic queue in which the job is executing. SMB$ENTRY The entry number of the JOB. SMB$USERNAME The USERNAME of the submitting process. SMB$UIC The UIC of the submitting process. SMB$FILESPEC The P1 argument if the FILE= parameter is specified in the queues configuration entry. Otherwise this variable is a null string. .EL .s .lm -5 Below is an outline of each of the non-special parameters, their meaning, and their purpose. .! .send toc .ifnot global .hl 3 ^&quepri\& .send toc .endif global QUEPRI is the priority at which the tasks executing in this queue will be execute at. Note that all processes are created using the DEFPRI sysgen priority, and a SET PROC/PRIO command is sent to the process to set it to this priority. This means that a process can raise it's priority back to DEFPRI or higher depending on privileges. .! .send toc .ifnot global .hl 3 ^&file\& .send toc .endif global FILE is the command file that the symbiont should invoke instead of the one specified as the P1 argument to SUBMIT or PRINT. This file specification is executed as a DCL command procedure. It is passed the arguments that were specified in the /PARAMETERS=() qualifier. The other information available includes the file specification that was SUBMIT'd or PRINT'd. The GLOBAL DCL symbol, SMB$FILESPEC, contains that file specification. .! .send toc .ifnot global .hl 3 ^&pause\& .send toc .endif global PAUSE is a length of time to delay the processing of the next job in a queue by waiting the specified number of seconds before reporting the TASK__COMPLETE after it has actually completed. .! .send toc .ifnot global .hl 2 ^&Special Configuration Parameters\& .send toc .endif global The following items are specific to the process running in a queue, and therefore make it impossible for a process created with any of these values specified, to be used by any other queue. .! .send toc .ifnot global .hl 3 ^&output\& .send toc .endif global OUTPUT is the output file specification that should be used for SYS$OUTPUT when the $CREPRC is done to create a new process for a queue. The default file specification is defined to be CTLSMB$ROOT:[LOG]STARTUP.LOG. If you desire to use the user= qualifier, then you must specify a device and file specification that is valid at the time that the process is created. e.g. SYS$LOGIN:FOO.LOG probably won't do what you want because SYS$LOGIN is not defined when the process is created. To get around this, you can define the file as NLA0:, and then use DEFINE or ASSIGN to redefine SYS$OUTPUT in the command procedure that is executed in the created process. .! .send toc .ifnot global .hl 3 ^&error\& .send toc .endif global ERROR is the output file specification that should be used for SYS$ERROR when the $CREPRC is done to create a new process for a queue. CTLSMB$ROOT:[LOG]STARTUP.LOG. If you desire to use the user= qualifier, then you must specify a device and file specification that is valid at the time that the process is created. e.g. SYS$LOGIN:FOO.LOG probably won't do what you want because SYS$LOGIN is not defined when the process is created. .! .send toc .ifnot global .hl 3 ^&expire\& .send toc .endif global EXPIRE is the maximum amount of time that a process created for use by a queue, can sit idle before it is deleted. The time is specified in seconds. The default configuration value is 600 seconds (10 minutes). This value is most useful for use in queues that use the 'user=user' qualifier to execute each process as the submitting user. In this case, the 'expire=' qualifer will allow these process to be expired quickly so that excess processes do not accumulate as different users make use of the queue. .! .send toc .ifnot global .hl 3 ^&detached\& .send toc .endif global DETACHED causes a detached process to be created rather than a subprocess to the symbiont. Normally, the symbiont creates subprocesses to process a given task. If you desire a queue to create detached processes as opposed to subprocesses then you should specify this flag. If you use the 'user=' option, then you MUST use detached processes to get a process that has the USERNAME specified by the 'user=' value. A detached process is also convienent to use when you need higher quota values that can not be supplied by the symbiont. .! .send toc .ifnot global .hl 3 ^"as\& .send toc .endif global Astlm, biolm, bytlm, cpulm, diolm, enqlm, fillm, jtquota pgflquota, prclm, tqelm, wsdefault, wsextent, wsquota are used to specify process quotas. These values are described in the $CREPRC system service description. You may specify any of these values, but the constraints layed out in the $CREPRC description always apply. I.E. some do not make sense for subprocesses, so you may need to create a detached process to get a specific quota value. .! .send toc .ifnot global .hl 3 ^&user\& .send toc .endif global USER allows a specific username (and UIC) to be associated with a created process. The argument of this options is a USERNAME from the SYSUAF.DAT file, or the special string, 'user'. If the string is NOT 'user', then ALL processes created in the specified queue will be created under the UIC of the USERNAME specified. The processes will also be given the priviledges of the USERNAME specfied. .s If the string IS 'user', then for each task, a process will be created under the submitting USERNAME's uic with the priviledges specified in the SYSUAF.DAT file. Note that the use of the 'detached' parameter determines whether the USERNAME of the process, in either case, is SYSTEM or that indicated by the qualifier. .! .send toc .ifnot global .hl 2 ^&File format\& .send toc .endif global The configuration information is stored in the file CTLSMB$ROOT:[DAT]CONFIG.DAT. The format of that file is as follows. Comment lines begin with a '!'. An entry begins on a line that contains neither a '!' nor a blank as the first character. All characters up to the first blank, on such a line, comprise the name of the queue that that entry is for. Each parameter contains no blanks unless the value of the parameter is given inside '"' characters. Doubling of '"' characters is allowed, and yields a single '"' character. Each parameter is separated by a ','. If an entry must be continued across a line, then the first character of the continuation line must be a blank. An entry may have embedded comment lines by placing a '!' at the beginning of the line that is the comment. The last parameter of an entry should have NO trailing ','. Below is a sample configuration file. .! .send toc .ifnot global .hl 3 ^&Sample configuration file\& .send toc .endif global .S .LT ! ! This is the CTLSMB symbiont configuration file for each queue ! ! ! The local pmdf queue is used to deliver mail on the local channel. ! It uses a reduced priority because there is no need for a higher ! priority. ! pmdf_local quepri=4, file=pmdf_root:[exe]batch_monitor.com, output=pmdf_root:[log]localq_start.log, error=pmdf_root:[log]localq_start.log ! ! The pobox pmdf queue is used to run MASTER, RETURN, and POST in. ! Since MASTER for phonenet connections runs here, the priority must ! be up with the users so that there is not a protocol timeout problem. ! pmdf_pobox quepri=5, file=pmdf_root:[exe]batch_monitor.com, output=pmdf_root:[log]poboxq_start.log, error=pmdf_root:[log]poboxq_start.log ! ! The MAIL$BATCH queue is used by PMDF to process deliver usage and other ! things that require things to run on behalf of non priviledged users. ! mail$batch user=user, output=NLA0:, error=NLA0:, detached, expire=45 ! ! The IBM RJE queue uses a detached process so that the USERNAME of the ! created process will be that of the submitting user. That way, MAIL ! will place the proper return address into the message. It uses a ! reduced priority because there is no need for urgency. It expires ! processes rapidly because the created process is special, and is of ! limited use. ! ibm$dispatch user=user, file=pub$root:[ibm]dispatch.com, output=NLA0:, error=NLA0:, detached, expire=45, quepri=4 .EL .s The file, PMDF_ROOT:[EXE]BATCH_MONITOR.COM, used by the PMDF queues for processing requests looks like this. .! .send toc .ifnot global .hl 3 ^&Sample queue command procedure\& .send toc .endif global .S .LT $! $! Command procedure to set in front of POST, MASTER and RETURN. It $! defines the proper logfile redirection since Server queues do not $! support the notion of a logfile. Also, then ON THEN GOTO other $! statements allow any procedure to be envoked within the command file. $! $! Written by Gregg Wonderly 29-OCT-1987 $! $! $ fn=f$PARSE(SMB$FILESPEC,,,"NAME") $ on error then goto other $ on severe_error then goto other $ on warning then goto other $ goto process_'fn' $ process_: $ EXIT $ ! $ process_MASTER: $! $ define sys$output pmdf$root:[log]'p1'_master.log $ define sys$error pmdf$root:[log]'p1'_master.log $ @'SMB$FILESPEC' "''p1'" "''p2'" "''p3'" "''p4'" "''p5'" $ deassign sys$error $ deassign sys$output $ EXIT $! $ process_POST: $! $ define sys$output pmdf$root:[log]post.log $ define sys$error pmdf$root:[log]post.log $ @'SMB$FILESPEC' "''p1'" "''p2'" $ deassign sys$error $ deassign sys$output $ EXIT $! $ process_RETURN: $ define sys$output NLA0: $ define sys$error NLA0: $ @'SMB$FILESPEC' "''p1'" "''p2'" $ deassign sys$error $ deassign sys$output $ EXIT $! $ OTHER: $ on error then stop $ on severe_error then stop $ on warning then stop $ @'SMB$FILESPEC' "''p1'" "''p2'" "''p3'" "''p4'" "''p5'" "''p6'" $ EXIT .EL .! .send toc .ifnot global .hl 1 ^&Installation\& .send toc .endif global Installation of CTLSMB is straight forward. You should read the contents of the tape into a directory suitable for your sites needs. .! .send toc .ifnot global .hl 2 ^&Creating a New Executable\& .send toc .endif global You can examine the file CTLSMB$ROOT:[SRC]DEFS.INC to see that the values given by the constants defined there are suitable for your sites' needs. The comments there should clarify the meaning of each value. If you change any of the values, then you must recompile the symbiont. To do this, SET DEFAULT to the [.SRC] subdirectory and issue the command, @MAKE. When this command completes, then you can purge the old files and go to the next step. .! .send toc .ifnot global .hl 2 ^&Installing the Symbiont\& .send toc .endif global The symbiont image MUST reside is SYS$SYSTEM. The command file, [.SRC]MAKE.COM will copy it there for you. Use the command '@MAKE INSTALL' to do this now. .! .send toc .ifnot global .hl 2 ^&Creating queues\& .send toc .endif global Queues that use CTLSMB must be initialized differently than standard BATCH or PRINTER queues. If you desire to have a JOB_LIMIT facility, like BATCH queues, then you must create a generic queue that will be served by the required number of CTLSMB, SERVER queues. In all cases, the configuration file entries correspond to the executor queue name, which may not be the name of the queue that the job was submitted, if the queue is generic. A few examples will help to clarify things. .s If you desire to create only /JOB_LIMIT=1 type queues, then each one can be created using a DCL command similar to: .lm+5 .s $ INITIALIZE/QUEUE/PROCESSOR=CTLSMB - .br __$ /SCHEDULE=NOSIZE .s .lm -5 You should replace with the name of the queue that you wish to create. .s NOTE: If you do not wish public access to this queue, then include the appropriate /PROTECTION and/or /OWNER qualifier on the above command so that only the desired users have access. .s If you wish to create a /JOB_LIMIT=n, where n > 1, queue, you must use the generic feature of the JOB controller. First, you must create the queue which users will interface with. As an example, let us say that we wish to create a queue for serving file printing activities across some foreign network. We wish to have the users print their jobs to the queue NET$PRINTER. We would also like to have at most 3 print jobs active at any one time. The following DCL commands would allow us to do this. .lm +5 .s $ INITIALIZE/QUEUE/SCHEDULE=NOSIZE - .br __$ /GENERIC=(NET_1,NET_2,NET_3) NET$PRINTER .b $ INITALIZE/QUEUE/ENABLE_GENERIC - .br __$ /PROCESSOR=CTLSMB/SCHEDULE=NOSIZE NET_1 .b $ INITALIZE/QUEUE/ENABLE_GENERIC - .br __$ /PROCESSOR=CTLSMB/SCHEDULE=NOSIZE NET_2 .b $ INITALIZE/QUEUE/ENABLE_GENERIC - .br __$ /PROCESSOR=CTLSMB/SCHEDULE=NOSIZE NET_3 .s .lm -5 These commands create 4 queues. The first queue is the users' access point for the other 3 queues. Anytime that a user submits a job to NET$PRINTER, the three other queues will be examined for activity. If any one is idle, then the job will be started in that queue. If none are idle, the job remains queued for execution in the NET$PRINTER queue until a queue is available. The /SCHEDULE=NOSIZE switch is necessary to keep jobs from being ordered in the queue according to size. The VMS DCL dictionary explains the use of INITIALIZE/QUEUE in more detail. .! .send toc .ifnot global .hl 1 ^&The CHKACC program\& .send toc .endif global The CHKACC program is for use in command procedures that must check the accessibility of a file/device/image-section on behalf of another user. The HELP file for CHKACC describes the usage of the command line options. When using CHKACC, you should always make sure that you specify the proper information. A /PROTECTION=() qualifier should ALWAYS be present to ensure that that appropriate checks are made. .! .send toc .ifnot global .hl 1 ^&Comments welcome\& .send toc .endif global Your comments and suggestions for improvements are always welcome. On the Internet the author can be reached at gregg@NEMO.MATH.OKSTATE.EDU U.S. Mail is also welcome at the following address: .s 1 .lm+5 Gregg Wonderly .br Mathematics Department .br 401 Mathematical Sciences Building .br Oklahoma State University .br Stillwater, Oklahoma 74078 .lm-5