Security/3000 Help

                               SECURITY / 3000

                                  User Manual

                                 (Version 28.)

                              Copyright (C) 1981
                             Current printing 1999


Eugene Volokh

                          Written by Eugene Volokh
                   Vice President, Research and Development


VESOFT address, phone, FAX
Technical Support

                                VESOFT, Inc.
                             1135 S.  Beverly Dr.
                        Los Angeles, CA 90035-1119 USA
                             Phone (310) 282-0420
                              Fax (310) 785-9566

DISCLAIMER

The information in this document is subject to change without notice.  VESOFT,
Inc.  makes no warranty of any kind with regard to this material, including,
but NOT limited to, the implied warranties of MERCHANTABILITY and FITNESS FOR A
PARTICULAR PURPOSE.

VESOFT, Inc.  shall not be liable for errors contained herein or for incidental
or consequential damages in connection with the furnishing, performance or use
of this material.

(You may purchase additional copies of the manual directly from VESOFT or
VESOFT's representatives.)

This manual was formatted with PROSE, ROBELLE Consulting, Ltd.'s excellent text
formatter.  Thanks to ROBELLE for allowing us to use it.


Introduction: Why you need to improve your security``contents`news
Introduction: Why you need to improve your security
trouble with system security is that the need for it is often not obviously
apparent.  If your system's running slow, you know that you need to do
something about it; if you're running out of disc space, you can see that it's
happening; but your system may remain insecure for years and only when a
security violation occurs (and is detected, which might be many months later!)
do you realize that you needed security all along.

But then it's too late.

SECURITY LOOPHOLES YOU SHOULD BE AWARE OF:

LOGON RELATED LOOPHOLES

Logon security is very important because

   All other aspects of security rely on logon security.  If that is
   compromised, all other security is compromised as well since all subsequent
   security is based on the original logon user ID.

Logon security is simply all the security checking that happens at log-on time,
so anything that compromises such checking should be considered a logon-related
loophole.  MPE provides the ability to place a password on each logical user of
a system; however,the default out-of-the-box configuration has very few, if
any, passwords set, so any non-passworded user ID (IDentification) is a
probable logon loophole.

MPE passwords have other weaknesses as well:

  * They are stored in the system directory in plain text, and when the system
    is backed up to tape using the ;DIRECTORY option, the directory is written
    without any special encoding.  Therefore, anyone who can get a copy of your
    backup can take it to another system to read and discover your passwords!

  * Since there is only one password for each MPE user ID, any time two or more
    people must share an ID (such as for CLERK.PAYROLL), there is an increased
    chance that the password will spread out to more people than are authorized
    to use it.

  * Although there are three possible passwords for each logon, one is rarely
    used (if ever) and another must be shared amongst several users.  This
    means that there is really only one password that protects each USER ID.
    The three passwords are:

    - The USER password, which is generally unique for each physical user
      UNLESS you have several "CLERK.PAYROLL" types of USER IDs

    - The ACCOUNT password, which must be shared amongst all users of an
      account, and is therefore subject to rapid spreading to non-account
      users.

    - The GROUP password, which even though it may be set, is not required if
      you are logging on to your "HOME" group! Because of this, this password
      is rarely used at all.

  * They don't protect a system from "brute force" violation attempts where an
    intruder simply keeps trying various passwords until a valid password is
    found.  This is due mainly to the fact that MPE does nothing other than
    print a message on the system console reporting the incorrect password
    attempt.  Since this message looks like nearly every other message
    (requesting tape mounts, successful logons, and other similar message
    traffic), it is very likely that these violation attempts will go on
    unnoticed until it is too late.  (This is especially true if the hacker is
    trying on a Saturday when there is nobody in the computer room to even see
    these messages!)

  * They don't protect your application(s) from "internal" intrusion (where
    legitimate employees or users of the system log on to areas where they are
    not authorized or use programs and utilities that lets them access critical
    information).  For instance, if someone logs on to the payroll account from
    the accounts receivable office, there is a good chance that the logon is
    really a security violation.

In order to combat these loopholes, a separate program should be run at logon
time to validate the user with additional passwords, time and day checks,
invalid attempt counts, and other similar security measures.  Since such a
program is not part of the operating system as shipped by HP, the security
administrator must ensure that this program is run every time a user logs on,
evaluate the result, and either allow the user to proceed or log the would be
intruder off of the system.  Additionally, the program should be protected from
the user simply pressing [BREAK] and aborting the program/UDC.  Fortunately, it
is not very difficult to ensure that these steps are taken as MPE provides
options to UDCs that allow you to do this.  If OPTION LOGON in a UDC is
specified, the operating system will execute the UDC every time you log on;
OPTION NOBREAK disables the use of the [BREAK] key while the UDC is executing.

Despite these options, however, there is still one thing to consider: SM users
on MPE/iX systems are able to bypass OPTION LOGON UDCs completely by specifying
a negative ;PARM= parameter (such as -1 or -2) on the HELLO command they use to
access the system.  Since the OPTION LOGON UDC will not be executed, no
programs will be run at logon time, so there is no checking beyond the normal
MPE checks.

NETWORK RELATED LOOPHOLES

Networks and modems which allow access to the computer from physically remote
locations have additional security issues to consider.  Some things that
generally don't apply to direct in-house connections are as follows:

  * In-house connections can be physically monitored to be certain that only
    employees are using them; modems and network connections cannot be
    monitored as easily.

  * Since you don't know the exact location of the person logging on from a
    network or modem, you should not allow access to sensitive applications
    from these sources.

  * Since some information about the original logon from a remote computer is
    available for network originated logons, many security administrators relax
    the rules somewhat by not requiring the user to re-enter passwords if the
    local and remote logon is identical.  However, you should be aware that the
    more convenient it is to logon, the less secure your system is overall.

  * Some network file-transfer programs violate system security by logging on
    to an HP3000 without invoking the OPTION LOGON UDC.  Although this is not
    technically a security violation (you still have to provide MPE passwords),
    any additional security measures that are implemented by using an OPTION
    LOGON UDC will be side-stepped, thus allowing a user to transfer
    potentially dangerous programs to your system or steal sensitive data files
    from your system.

BATCH RELATED LOOPHOLES

The HP3000 allows users to place a series of commands into ASCII file to
execute while they are busy with other tasks or to schedule for execution at a
time when they do not intend to be present.  This places an additional burden
on the security system since the user need not be physically present at the
time the JOB launches, so the job must be pre-validated before it can be
submitted.

Generally, this is done by including the MPE password in the file of commands
to be executed.  Again, these passwords are written in plain text (like they
are in the system directory); however,these files can often be read without
first copying them to another machine, so every such file that contains an
embedded password is a BATCH loophole waiting to be exploited!

Furthermore, every file that contains a password makes it that much more
difficult to actually change a critical password since each and every file must
be edited to reflect the new password whenever it is changed.

UNATTENDED TERMINAL LOOPHOLES

People often remain logged on to the computer even when they're not actively
using it.  This can cause several problems:

  * Unattended terminals can be a grave security threat.  An unattended
    logged-on terminal can defeat the best security system; anybody can come up
    and use it without having to re-logon and specify any passwords.

  * On some systems, if a user "hangs up" on a modem connection without first
    saying BYE, the next user to dial-in to that port is simply dropped into
    the first user's session, without having to enter any passwords!

  * If you have a local area network, unattended terminals can waste precious
    ports.

  * Each session uses a good number of system table entries (DSTs, PCBs, etc.)
    and virtual memory.  Sites that are running into system table limits are
    often the victims of users who consume system resources even though they're
    not actively using the computer.

APPLICATION LOOPHOLES

Once a user has successfully logged on with a correct and proper password (from
their terminal, during normal business hours, etc.), what next? MPE displays a
short block of text announcing what version of the operating system the user
has logged onto, then leaves the user at what is commonly known as "The Colon
Prompt" (This is for historical reasons since on MPE/iX machines the prompt can
be re-configured to be almost anything).  At this point, the user can make
further attempts at determining sensitive information with little or no
supervision since every non-console command and unprotected utility is
available to the user.

This is almost like having all of your security guards at the front gate, but
once a person is admitted, they are free to roam around at will...

Unfortunately, some applications presume that once a person has logged on with
a valid USER ID, they are authorized to do just about anything.  However, just
because a person knows the correct :RUN command to start the application
doesn't mean that they should be able to do "anything".  Also, some programs
(such as QUERY) allow users to manipulate data files outside of the application
itself.  This can be quite dangerous as there may be bits of data that the user
of an application never sees (pointers to related records, for instance), so by
changing the data without the benefit of the application program verifying the
transaction, you may end up with corrupted data files.

SECURITY/3000 FEATURES

Before you decide what security features you need for your installation, please
consider the following questions:

   * Do your users log on as "JOE.PAYROLL" (with the person being uniquely
     identified by the MPE user name) or as "JOE,CLERK.PAYROLL" (with the
     person being uniquely identified by his session name)?

     If you use the session name approach (as probably many of all MPE users
     do), then you must have a security system oriented around session names.
     What's the use of MPE user passwords if you share them among fifty users?
     You must have passwords that are tied to each person, which means that
     they must be tied to the session name.

     (This way, you'll also avoid the annoying habit that people sometimes have
     of omitting their session names at logon time [since MPE considers them to
     be optional]; in fact, if you don't use session names because they're
     unenforceable by MPE, SECURITY's session name security can allow you to
     use them.)

   * How often do you change your passwords?

     Passwords only protect you if they're known only to those who are
     authorized to know them.  Over time, however, passwords spread out "over
     the grapevine"; after a few months, they're probably known to far more
     than just the person who's authorized to know them.

     Many auditing departments wisely establish standards that require
     passwords to be changed periodically, e.g.  at least once every month.
     Since this is obviously too much of a burden for an account manager to
     undertake manually, there must be some way to automatically force users to
     periodically change their own passwords.

   * Do your users have access to MPE prompt?

     The majority of all application users should not have access to MPE prompt
     (other than to type the :HELLO command).  They certainly don't need access
     to all the power of MPE commands -- in fact, ":" access will only confuse
     them.  Giving them such access means they can :LISTF any file in the
     system, accidentally (or intentionally) read, modify or purge critical
     files, run QUERY, and do a lot of other mischief.

     If a particular user is supposed to do only one thing (e.g.  run the
     Accounts Payable system), you can quite reasonably set up an OPTION LOGON,
     NOBREAK UDC that runs whatever program needs to be run and then does a
     :BYE.  However, what if the users need to, say, run either the A/P system
     or the G/L system? Or, perhaps, issue a :TELLOP command or do a :SHOWJOB?

     The wrong thing to do is to give them ":" access -- the right thing is to
     give them a menu of options that they can use and nothing else.  In
     addition to the extra security, logon menus will make your users' lives
     much easier!

   * How do you protect your dial-in lines?

     Dial-in access to your computer poses problems of its own.  When somebody
     accesses your system from a hardwired terminal, you at least know that
     he's not some stranger off the street; however, any former employee or
     high school hacker could conceivably figure out your dial-in phone number
     and access your computer without any monitoring or supervision.  Dial-in
     access therefore requires an additional level of security.

     SECURITY allows you to impose a password (or passwords) on a
     terminal-by-terminal basis, thus letting you require an extra password for
     dial-in access.  Also, you may restrict to which MPE user and account a
     dial-in user may log on.  What's more, you may even tell SECURITY to
     automatically shut down any device (e.g.  a dial-in line) or user for
     which there have been more than a certain number of consecutive
     unsuccessful logon attempts.  This way, if somebody is using your dial-in
     line to try to guess your passwords, SECURITY can forbid all access to the
     terminal (or to the specific user ID) after, say, 3 or 5 consecutive
     password errors.

   * Do you have a "network" of several different types of computers?

     If so, you may have many of the same problems associated with dial-in
     lines without even knowing it! Users connected to a terminal on one
     particular computer may have access to a program that allows them to log
     on to your HP3000 just as if they were at a hard-wired terminal.  Since
     these users are at a different computer (which is probably at a different
     site), they are just as "invisible" to a security administrator as someone
     at the end of a phone line.  In addition, many file transfer protocols
     allow users to transfer files without actually logging on to the target
     computer!

   * Do you have a network of two or more HP3000s?

     Even if all of your computers in your network are HP3000s, you may have
     difficulty keeping passwords and profiles consistent between one machine
     and the next.  SECURITY has a special set of programs designed to keep
     your network synchronized.

   * Do you have embedded passwords?

     Along with shared passwords and passwords that have not been changed for a
     long time, embedded passwords are one of the greatest threats to your
     system security.  Once you embed a password into a job stream or a
     program, that password becomes much easier for somebody to figure out and
     virtually impossible to change (unless you're willing to modify all the
     job streams and programs that might have it).

     The "STREAMX" module lets you prompt for job stream passwords at
     :STREAM-time, thus avoiding the need for embedded passwords. Actually,
     this is just the tip of the iceberg for STREAMX -- STREAMX has extra
     provisions which, for example, allow console operators to stream jobs even
     though the passwords aren't embedded and the operators aren't supposed to
     know them, and many other valuable security features.

   * Would you like to have a "Job Stream Programming Language" that can make
     your job streams much "smarter"?

     With STREAMX, you can set up very sophisticated job streams that prompt
     for user input, check it for validity, check the environment to make sure
     all the files needed for the job stream are present, etc.  And it can
     perform SCHEDULING too ...  As you see, STREAMX is a very powerful
     productivity tool (as well as a security tool).

   * How do you protect your databases?

     In the overwhelming majority of HP3000 sites, most of the very important
     and sensitive data is kept in IMAGE databases.  Unfortunately, although
     IMAGE has a very complicated security system built into it, very few
     people use it because it's based on passwords which must be embedded into
     all programs that access the databases.

     This makes these passwords very easy for people to figure out and very
     hard to change; what's more, since the passwords are kept inside the
     program, all users running the program get the same level of IMAGE access.

     SECURITY's VEOPEN facility lets you protect databases
        *by program,
        *by user,
        *by mode of access
     without requiring embedded database passwords.

   * What if a user walks away from his terminal?

     You can have a very elaborate logon security system, but if somebody walks
     away from his terminal, thus allowing another person to come along and use
     it, all the logon security will be for nothing.  The person who walks up
     won't have to re-logon, specify his passwords or whatever -- he'll be
     right in the middle of the original user's session, and be able to do
     anything that the original user could have done.

     The LOGOFF program allows you to automatically log off people whose
     terminals have been idle for a given amount of time.  This way, if
     somebody walks away from his terminal, you can be sure that, say, within
     15 minutes his session will be automatically terminated.  This can also be
     a very useful operations feature around backup time, when you want to make
     sure that everybody logs off the system.

   * AND MORE:

       - Thorough and easily reportable logging of logons, attempted security
         violations, job submissions, user additions, changes, and deletions,
         and other security-related events.

       - Terminal, day-of-week, and time-of-day restrictions that control where
         and when a user may log on (e.g.  only on the Accounts Payable-area
         terminals, Monday through Friday, 8 AM to 6 PM).

       - Enforcing minimum length and other standards on both MPE and SECURITY
         passwords.

       - Guaranteeing that all users on the system (or specific classes of
         users, e.g.  users with PM or SM capability) have MPE user passwords.

       - Allowing users to change their own MPE and SECURITY passwords, thus
         encouraging them to change passwords as often as possible.

       - Forbidding several sessions logged on with the same session name, user
         ID, and account name (which usually means that a user has walked away
         from one terminal to go to another).

       - :ALLOWing console commands not to everybody but on a user-by-user
         basis.

       - Imposing system-wide session name standards that prevent lazy users
         from omitting their logon session ID (this is an alternative to the
         Session Name security feature mentioned above).


Getting on-line help on SECURITY ``contents
Getting on-line help on SECURITY
SECHELP, MAIN.PUB.VESOFT entry point

VESOFT's HELP facility is conceptually oriented; there are very many --
literally thousands -- of keywords you can get help on.  It lets you read this
entire manual online.  To use the online help, type:

   :RUN MAIN.PUB.VESOFT,SECHELP

SECURITY will then prompt you with:

   What topic would you like help on (single word only)?

At this point you should type a word (or the first few characters of the word)
that you want help on.  For example:

   What topic would you like help on (single word only)? DEACT

You are then presented with a menu of all the help entries that refer to DEACT:

   Help is available on:
     1.  DEACTIVATE, %SEC command
     2.  $VE-DEACTIVATE, SECURCON.DATA.VESOFT keyword
     3.  $TERM-DEACTIVATE, SECURCON.DATA.VESOFT keyword
   Which of the above would you like help on?

You can then choose the entry that best describes what you want and enter its
number.  The program will then print the manual page that contains the topic
you selected, followed by this prompt:

(F)orward,(B)ack,(>)forward 1/2 page,(<)back 1/2 page,(M)enu,(E)xit?

This lets you page forward and backward through the manual to read the entire
section pertaining to your selection.

When you're done reading the manual, you can type "E" to get back to the "What
topic?" prompt or "M" to get back to the DEACT keywords menu we showed above
(in case you realize you chose the wrong option).

A few special keywords you can get help on are:
   INTRODUCTION         lets you choose one of the introductions
   CONTENTS             on-line access to the Table Of Contents
   NEWS                 new features of SECURITY

You can also get help when using the SEC entry point:

   :RUN MAIN.PUB.VESOFT,SEC
   %SEC HELP [keyword]

where "[keyword]" is the topic you would like to get help on.

If you are a user of MPEX as well as SECURITY, you can, within MPEX, say

   %SEC HELP [keyword]

to obtain help on the given keyword.

Note that this online HELP index is even more useful than the index in the back
of this manual, since the %SEC HELP command finds all the index entries that
are related to the given keyword (not just those that start with that keyword).


Introduction: Logon Security``contents
Introduction: Logon Security

There are many types of security -- each addresses different aspects of your
security requirements:

   * MPE's file access restrictions provide FILE security;

   * IMAGE (and our VEOPEN) provides DATABASE security;

   * LOGOFF, which aborts sessions that have been idle for a certain amount of
     time, implements UNATTENDED TERMINAL security.

However, in many respects one of the most important types of security is LOGON
security.

Logon security is simply all the security checking that happens at log-on time.
MPE passwords are a well-known aspect of logon security, but other aspects
include session passwords, terminal passwords, password obsolescence,
time-of-day / day-of-week access restriction, deactivation of a user or a
terminal after a number of unsuccessful logon attempts, and so on.  LOGON
security is very important because

   All other aspects of security rely on logon security.  If that is
   compromised, all other security fails, too, since all subsequent security is
   based on the logon user ID.

For instance, file or database security can make sure that, say, only MGR.AP
can access your Accounts Payable database in a certain way; however, if anybody
can log on as MGR.AP, this file/database security is useless.  Similarly, your
programs can look at a user's session name and give him access to the
appropriate program function (e.g.  only JOHN and MARY can print payroll
checks) -- however, if there's no logon security to make sure that only John
can log on with session name JOHN, your application system security won't do
any good.

There are a lot of things that SECURITY's logon facility provides you; you can
use some or all of them, in any combination you like:

   * Session name security, which lets you put passwords not just on MPE user
     IDs and accounts, but also on individual session names (e.g.
     JOHN,CLERK.AP).  This is vital if you identify your users by session name
     rather than MPE user ID.


Security passwords, one-way encryption``encrypted`one`way
Security passwords, one-way encryption

  * Encrypted passwords, which can never be decrypted and read by anybody.  We
     use a special "one-way" encryption algorithm in which the original
     password can not be determined from the encrypted value.

   * Password expiration, which guarantees that passwords (both MPE and
     SECURITY) must be changed every certain number of days.  This also allows
     a user to change his own passwords -- essential if you don't want to
     burden the account manager with having to change fifty people's passwords
     every month.

   * Password history, which guarantees that a user may not reuse the same MPE
     password for a certain amount of time (e.g.  half a year or a year).  This
     is a useful complement to Password Expiration, since it prevents people
     from switching back and forth between two passwords.

   * Terminal passwords, which can protect especially sensitive devices, like
     dial-in lines, consoles, and DS, NS, and LAN devices.  In addition,
     terminal/user restrictions allow you to restrict which user IDs dial-in
     users may use (e.g.  anybody who logs on using the dial-in line and
     specifies the password SUSANNAH can only log on to the DEV and PROD
     accounts).

   * Logon menus, which prevent a user from ever seeing the command interpreter
     (MPE prompt) and restrict him to a fixed list of options he can execute.
     Thus, you can make sure that your users can only run the programs and
     execute the commands that you want them to, rather than have access to all
     the power of MPE.

   * Terminal deactivation, which entirely forbids access on a terminal after
     some number of consecutive unsuccessful logon attempts (until the console
     operator brings the terminal back up).  This way, if somebody is using a
     dial-in line to try to guess your passwords, you can specify that after,
     say, five consecutive password errors, the terminal will be shut down, and
     no further logon attempts can occur until the console operator brings it
     back up.

   * User deactivation, which entirely forbids access to a particular user ID
     after some number of consecutive unsuccessful logon attempts (until the
     account manager reactivates the user ID).  This way, if somebody's
     unsuccessfully trying to guess a particular user's passwords, you can
     entirely prevent any further logon attempts for that user until the
     account manager reactivates him.  This can be a useful alternative to
     Terminal Deactivation (described above).

   * Logging: SECURITY maintains a special log file that records attempted
     violations, batch job submissions, and password or profile changes.  You
     can then easily extract data from that log file, e.g.  "show me all the
     logons of users with session name JACK on terminal 20 in the month of
     November".

   * Terminal, day-of-week and time-of-day restrictions, which let you indicate
     which terminals, which days of the week, and which times of the day a
     particular user may log on.  For instance, you can indicate that
     JANE,MGR.PAYROLL can only log on to LDEVs 61, 62, 63 and 65 (the payroll
     terminals), only Monday through Friday, and only from 8 AM to 6 PM.

   * Prevention of concurrent sessions, which guarantees (if you so wish) that
     you don't have two sessions with the same logon ID (session name, user
     name, and account name) logged on at the same time.  Such concurrent
     logons usually mean either that the user is logged on to one terminal and
     has left it unattended to log on to another terminal (which is a bad
     thing) OR that one user is attempting to log on using another's logon ID
     (which is also bad).

   * The ability to :ALLOW console commands not on a system-wide but on a
     user-by-user basis.  Normally, MPE only lets you set permanent :ALLOWs of
     console commands on a system-wide basis -- however, what you really want
     to do is to grant :ALLOWs for specific things to specific users.  SECURITY
     permits you to do this; not only does it therefore improve your system
     security, but it makes things more convenient because you can now :ALLOW
     specific users commands that you'd be afraid to :ALLOW to everybody.

   * Configuring a single person to be able to log on into several places.  You
     can allow a person to log on under several different MPE user IDs -- e.g.
     JACK,CLERK.PAYROLL, JACK,MGR.AP, and JACK.PROD -- and specify his password
     ONCE.  Then, whenever his password is changed, SECURITY will automatically
     change it in all the appropriate places.


How logon security works ``contents
How logon security works
Setting the SECURITY logon UDC file LOGONUDC.PUB.VESOFT

To implement SECURITY's logon module, we supply a UDC file called
LOGONUDC.PUB.VESOFT.  We recommend that this be set at the SYSTEM level as
follows:

   :SETCATALOG LOGONUDC.PUB.VESOFT;SYSTEM

This :SETCATALOG causes the program MAIN.PUB.VESOFT to be run with the LOGON
entry point every time somebody logs on.  This program then checks the various
SECURITY configuration options and performs the security checks that you've
defined for each user.  We recommend that this UDC be set at the SYSTEM level
to ensure that the program is run for all users.  If this UDC is not set at the
system level, then any users who log on where this UDC is not set will not be
authenticated and could (possibly) circumvent your security requirements.

(NEW) Securing MPE/iX systems WITHOUT using LOGON UDCs


Securing MPE/iX systems WITHOUT using LOGON UDCs``contents`news
Securing MPE/iX systems WITHOUT using LOGON UDCs

We have taken advantage of a new MPE/iX operating system Architected Interface
Facility known as Procedure Exits (AIF:PE) that allows us to run our LOGON
program whenever anyone logs onto the system, without requiring that you first
setup a system-wide UDC.

The %BACKG LOGON task allows you to control this alternate logon interception;
it operates quite independently of whether you have :SETCATALOGed our
LOGONUDC.PUB.VESOFT file or not.  Our use of AIF:PE does require you to be
using MPE/iX 4.0 or later.

To turn on logon interception using this method, simply issue the following
commands:

   :RUN MAIN.PUB.VESOFT,SEC
   %SEC BACKG STARTJOB (if it isn't already running)
   %SEC BACKG START,LOGON

Note that running with the ,SEC entry point causes our program to prompt with
"%SEC".  You can also issue the BACKG STARTJOB and BACKG START,task commands
directly from inside MPEX at its "%" prompt.

Once the %BACKG LOGON task has started, the AIF:PE LOGON trap is enabled and
will remain that way until a %BACKG STOP,LOGON command is issued or until the
system is stopped.  You must ensure that our BACKG job is streamed every time
your system is restarted: your system will not be protected by our LOGON
program after it starts until the BACKG job's LOGON task has started to
execute.

For this reason, it may be prudent to leave the LOGONUDC.PUB.VESOFT UDC file
:SETCATALOGed.  Even if you implement logon security using the AIF:PE technique
AND using the old UDC-based method, your users will only be prompted once for
passwords when they logon.

Please refer to the section "Activating HELLO trap automatically during system
start-up" for details on how to ensure that the BACKG LOGON task is started
automatically.

If the BACKG job aborts for any reason (i.e., aborted with an :ABORTJOB
command), the AIF:PE LOGON trap will remain active and continue to keep your
system secure.

The mere act of doing the :SETCATALOG or enabling the %BACKG LOGON task will
not automatically set all of SECURITY's features (session name Security,
password expiration, terminal passwords, etc.) for all your users; we realize
that you may very well want to configure some of these features for some users
and other features for other users.


MAIN.PUB.VESOFT, "LOGON" entry point
fact, if you just do the above :SETCATALOG (without specifying the security
options you want to use in the SECURITY configuration file), then nothing
special will happen.  The logon UDC will cause our MAIN.PUB.VESOFT program to
be run every time somebody logs on, but the program won't actually prompt him
for any extra passwords or do any extra checking until you explicitly turn on
some of SECURITY's security options.

Of course, if you have other system-wide UDC files, you should set them, too,
by saying something like

   :SETCATALOG LOGONUDC.PUB.VESOFT,yourfilename;SYSTEM

IMPORTANT: If you have your own OPTION LOGON UDC defined, setting our UDC file
first will override your OPTION LOGON UDC and your commands will NOT be
executed as users log on.  SECURITY provides a mechanism to automatically
execute commands at logon time (which can be customized on a user-by-user
basis) called $LOGON-EXECUTE.  For details on how to integrate your commands
into a $LOGON-EXECUTE command, see the section Automatically executing commands
at logon time.


SECURCON.DATA.VESOFT ``configuration
SECURCON.DATA.VESOFT
place where you indicate which security options and settings you want to
use is the file called SECURCON.DATA.VESOFT.  It's a normal MPE file --
modifiable using EDITOR -- and looks something like this:

   :PRINT SECURCON.DATA.VESOFT;NUM
        1  $LOG-LOGON @.@-@.DEV
        2  $VEPROFILE @.PROD @.AP
        3  $MPE-OBSOL @.DEV @.PROD CAP=SM CAP=PM
        4  $MPE-U-OBS-DAYS 30
        5  $TERM-DEACTIVATE 3 LDEV=23 LDEV=24 LDEV=61
        6  $PASS "LETMEON"  "TERMINAL PASSWORD" LDEV=MODEM&CAP<>SM
        7  $PASS "SECRETSM" "TERMINAL PASSWORD" LDEV=MODEM&CAP=SM

The things starting with "$"s are keywords, and each is followed by a number of
parameters indicating what settings these keywords have and for whom they are
effective.  For instance, the above file indicates that:

   * $LOG-LOGON @.@-@.DEV

     Successful logons are to be logged to the SECURITY log files for all users
     in the system except for those who log on to the DEV account.  As you see,
     the "@" means "all" (just as in MPE) -- depending on its place, it may
     mean "all users", "all accounts", etc.  The "-" between the "@.@" and
     "@.DEV" means "except" -- all users (@.@) except those in the DEV account
     (@.DEV).

     "@.@-@.DEV" is an example of a userset -- a kind of expression that
     specifies a collection of users.  Other examples of usersets include
     "MGR.AP" (referring to that specific user), "JACK,@.@" (anybody logging on
     with session name JACK), "LDEV=20" (anybody logging on to LDEV 20), and so
     on.

     For more information on usersets, see the Usersets chapter below.

   * $VEPROFILE @.PROD @.AP

     SECURITY's passwords -- one-way encrypted and applicable to session names
     as well as users -- are to be enforced for the PROD and AP accounts.  This
     means that everybody who logs on to the PROD and AP accounts will have to
     be configured in the SECURITY database (about which we'll talk shortly),
     and can have the benefit of session name security, logon menus, terminal/
     Day-of-Week/Time-of-Day Restrictions, etc.

   * $MPE-OBSOL @.DEV @.PROD CAP=SM CAP=PM

     Since SECURITY passwords can easily coexist with MPE passwords, we can
     indicate that MPE passwords are to be obsoleted (i.e.  will automatically
     expire) for all users in the DEV and PROD accounts and also any user who
     has SM or PM capability.  Note how flexible this is -- you can easily
     include and exclude exactly those users and types of users that you want
     to.

   * $MPE-U-OBS-DAYS 30

     Since we've just turned on MPE password expiration for some users, we can
     specify how often passwords need to be changed.  In this case, we indicate
     that they must be changed every 30 days for every password in the system;
     however, we could have easily specified different time frames for
     different usersets (e.g.  every 30 days for @.PROD and every 45 days for
     @.DEV).

   * $TERM-DEACTIVATE 3 LDEV=23 LDEV=24 LDEV=61

     This keyword indicates that Terminal Deactivation is to occur after 3
     consecutive unsuccessful logon attempts -- but only on LDEVs 23, 24 and 61
     (presumably dial-in lines).  Other terminals won't be deactivated.  Note
     again how flexible this is -- you can specify deactivation for some
     terminals and not for others, different deactivation parameters for
     different terminals, etc.

     (Terminal Deactivation means that after several consecutive unsuccessful
     logon attempts, the LDEV on which they occurred will be shut down until
     the system operator brings it back up.  This can prevent "hack attacks" in
     which would-be intruders try hundreds of passwords, hoping that they'll
     eventually reach the right one.)

   * $PASS "LETMEON" "TERMINAL PASSWORD" LDEV=MODEM&CAP<>SM
     $PASS "SECRETSM" "TERMINAL PASSWORD" LDEV=MODEM&CAP=SM

     These keywords indicate that the Terminal Password "LETMEON" is in effect
     for non-SM users logging on to LDEVs with device class MODEM; for SM users
     logging on to the same LDEVs, the password is "SECRETSM".

The SECURCON.DATA.VESOFT file we just showed is, of course, just an example --
you could have had more, less or different options in the SECURCON file.  Note
also that although SECURCON is an ordinary MPE file, it can't be accessed by
anybody except for SECURITY itself and users in the VESOFT account.  To modify
it, you have to be logged on to the VESOFT account; once you secure the VESOFT
account (using SECURITY passwords), you can be sure that only you (the system
manager) can change the SECURCON file.

As soon as you add, say, a $TERM-DEACTIVATE, a $ALLOW or a $LOGON-EXECUTE to
the SECURCON.DATA file, it automatically takes effect -- you don't have to run
any other program or enter any other data.  Other things, however, require some
additional steps.

In particular, consider the $VEPROFILE keyword we specified above.  All we said
was that SECURITY passwords (and, if you wish, session name security, logon
menus, terminal/day-of-week/time-of-day restrictions, etc.) would be enforced
for the PROD and AP accounts.  The actual SECURITY passwords, the session
names, the menu file names, the specific restrictions, and so on have to be
entered separately.

In other words, adding the $VEPROFILE to the SECURCON will enable SECURITY
password processing -- it won't actually specify the passwords or add the
"SECURITY user profiles" to our SECURITY database.  This has to be done
separately, in a manner which we will discuss in the SECURITY User Profiles
chapter below.

"User Profile" is a term we'll be using very often.  A user profile is really
an entry in a special SECURITY database.  This entry contains various
information about a particular user who's known to SECURITY (much like MPE
directory entries contain information, such as passwords, about MPE users).
This entry can be added, changed, deleted, and listed (by saying :RUN
MAIN.PUB.VESOFT,ADD or CHANGE or DELETE or LISTUSER); it is looked at by
SECURITY at logon time if the $VEPROFILE keyword has been added to the
SECURCON.DATA.VESOFT file.

Putting things another way, here's what will happen at logon time:

   * The user enters :HELLO ...

   * MPE prompts him for his MPE passwords (if any)

   * MPE runs MAIN.PUB.VESOFT,LOGON

   * MAIN.PUB.VESOFT reads the SECURCON.DATA.VESOFT file and enforces all the
     options kept there, like $MPE-OBSOL (MPE password expiration), $LOG-LOGON
     (logon logging), $PASS (terminal passwords), etc.

   * If the $VEPROFILE flag is set for the user, then MAIN.PUB.VESOFT looks up
     the user's SECURITY profile and enforces the profile options -- SECURITY
     passwords, logon menus, and terminal, day-of-week, and time-of-day
     restrictions

   * Finally, after all the SECURITY checks have been passed, SECURITY lets the
     user into MPE (or into a logon menu if one was configured for the user).

SECURITY User Profiles

One of the most powerful features of SECURITY is the ability it gives you to
define your own special SECURITY user IDs.  These user IDs are superior to MPE
user IDs in several ways:

   * They are SESSION NAME + MPE USER ID + ACCOUNT NAME rather than just the
     MPE user ID and account name alone (note, however, that they need not be
     tied to session name -- they can be based on the MPE user ID as well).

   * They can have special SECURITY passwords that are one-way encrypted to
     prevent anybody (even us!) from being able to read them, say, from a
     system dump or with any utility.

   * They can have multiple passwords -- rather than having just one user
     password, you can have several (each one with its own prompt).  Thus, you
     can define each user to have, say, three passwords, and a random one is
     asked each time he logs on; this way, if somebody does manage to figure
     out a password, he'll have no guarantee that the password he knows will be
     the one that will be prompted for.  (Some people use this mechanism to
     implement "personal profile passwords" -- passwords that are answers to
     personal questions like "What's your mother's maiden name?", "What
     elementary school did you go to?", etc.).

   * They can impose on each configured user terminal, day-of-week, and
     time-of-day access restrictions, e.g.  "JOHN,CLERK.PAYROLL can only log on
     to terminals 51, 52, and 57; he may log on only Monday to Friday, 8 AM to
     6 PM".

   * Finally, each SECURITY user can have specified for him a logon menu file,
     which he'll see as soon as he successfully logs on (instead of just
     getting the MPE prompt).  The user will then only be able to do those
     things that he is permitted to by the menu file.

Not all SECURITY features require a user profile to be added to the database --
MPE password obsolescence, terminal passwords, and many other things (discussed
later) work very well with existing MPE users and passwords.  However, to use
the specific features listed above, you have to set up user profiles.

SESSION NAME SECURITY


Session name security ``contents
Session name security

Say that all your users log on with session names, e.g.  JOE,CLERK.PAYROLL or
MARY,MGR.AP.  MPE user passwords are clearly inadequate for security, since
dozens of users will have to share them; the passwords will quickly become
known to everybody (how can you keep a secret that fifty people know?).

What's more, even if the passwords were restricted to those who were actually
authorized to log on as CLERK.PAYROLL or MGR.AP, there would be no way of
making sure that Joe really logs on with session name JOE rather than with no
session name at all or with somebody else's session name.

What you need is security based not just on MPE user ID, but also on session
name.  Obviously, however, it's not enough just to add a line to SECURCON
indicating that session name security should be turned on; you have to (at
least) somehow indicate what each session name's password is supposed to be.
Clearly you can't do that in the MPE directory (since it has only one entry for
each user ID); therefore, SECURITY has to have some way of defining special
SECURITY user profiles, with their own passwords, stored in the SECURITY
database.

ADDING USER PROFILES


Adding user profiles ``contents
Adding user profiles
ADD, MAIN.PUB.VESOFT entry point

Let's consider a practical example.  Let's say that all your AP account users
are supposed to log on with session names; some are supposed to log on as the
user CLERK and others as the user MGR.  Anybody who does not use a valid
session name/MPE user ID combination should be denied access; someone who does
use a correct session name and user ID should be prompted for his SECURITY
password.

First of all, you have to add the SECURITY user profiles to the SECURITY
database.  (Profiles are actually stored in a special file named
SECURG.DATA.VESOFT rather than an IMAGE database).  You do this by saying

   :RUN MAIN.PUB.VESOFT,ADD

Here is how SECURITY responds:

   SECURITY/ADD 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: CLERK
   Enter account: AP
   Enter session name: JOE
   Enter user's real name: JOSEPH STORY
   Enter permitted terminal numbers:     << hit [RETURN] >>
   Enter day-of-week access restrictions:     << hit [RETURN] >>
   Enter time-of-day access restrictions:     << hit [RETURN] >>
   Enter the menu file name:     << hit [RETURN] >>
   Enter Y if the user is to have SECURITY passwords;
         N if the user is not to have SECURITY passwords;
         A if the user is to have passwords, but should enter the
           correct passwords himself the first time he logs on.
   Your selection (Y/N/A)? Y

   PLEASE ENTER THE SECURITY PASSWORD:   << Joe enters it, no echo >>
   Please enter the answer again:    << enters again, for verification >>

   *** User has been added.  ***

   Enter user ID:     << hit [RETURN] to exit >>

What has this accomplished? This has defined a SECURITY user JOE,CLERK.AP with
the password which you entered.  Similarly, you can define, for instance, users

MARY,CLERK.AP,
PETE,CLERK.AP,
MELINDA,MGR.AP,    and
JOE,MGR.AP  (same PERSON as JOE,CLERK.AP, but with another MPE user ID)

Note that although these represent only two MPE user IDs, they actually have
five distinct SECURITY passwords, one for each configured SESSION + USER +
ACCOUNT logon.  (Note that SECURITY prompted us for a lot of other things --
terminal, day-of-week, and time-of-day restrictions and a logon menu file --
which we will discuss later; for clarity, in this example we don't enter any
such restrictions.)

Now that you've configured the AP account users, you may go into your
SECURCON.DATA.VESOFT file and add a line that says:


VEPROFILE, SECURCON file keyword
$VEPROFILE, SECURCON file keyword

   $VEPROFILE @.AP

This means that:

  * Whenever anybody logs on to the system in the AP account (indicated by
    @.AP),

  * his user profile will be looked up in the SECURITY user profiles database;

  * if it is not found, he will not be allowed to log on;

  * if it is found, he will be prompted for his SECURITY password (if we had
    entered any terminal, day-of-week or time-of-day restrictions or specified
    a menu file, these would take effect at this point, too).

By adding the "$VEPROFILE @.AP" line, you've just secured the AP account with
SECURITY user profiles.  If you want to, you can even remove all MPE passwords
from the AP account, because each valid logon to the account must have a
SECURITY profile, including appropriate passwords.  Note: if you plan to remove
MPE passwords, you will also need to enable $BATCH-VEPROFILE, documented
elsewhere in this manual; also, because of MPE/iX's :HELLO...;PARM=-1 feature
for SM users, you should have MPE passwords on all SM logons or enable our
HELLO trap.  You can use VEAUDIT to find all SM logons on your systems (see the
VEAUDIT User Manual for more details).

Note the two steps we went through:

   1. Set up all the user profiles with RUN MAIN.PUB.VESOFT,ADD.  This defines:

        - Which session names and user IDs can be used to log on (in our case,
          only JOE,CLERK.AP, PETE,CLERK.AP, MARY,CLERK.AP, MELINDA,MGR.AP, and
          JOE,MGR.AP);

        - what their passwords are;

        - what their menu files, terminal restrictions, day-of-week
          restrictions, and time-of-day restrictions are (see the Terminal,
          Time-Of-Day, And Day-Of-Week Restrictions chapter below).

   2.  Added to the SECURCON.DATA.VESOFT file the line

        $VEPROFILE @.AP

      This tells SECURITY that all users who try to log on to the AP account
      are to be validated through the SECURITY user profile database and are to
      be prompted for their SECURITY passwords.  Anybody who lacks a SECURITY
      profile will not not be permitted to log on.

Neither of these two steps would do the job if done alone.  If we only added
the profiles to the database, they would just sit there -- SECURITY would not
know that anybody logged on to the AP account is to be validated through the
database.

On the other hand, if we only added the $VEPROFILE line without adding the
profiles, nobody would be able to log on to the AP account at all -- whenever
anybody would try to log on, SECURITY would try to find his profile in the
database, and when it doesn't find it, would log the user off.  Remember, the
user profiles indicate more than just the passwords; they also indicate who can
log on to the account in the first place.  For example, SECURITY would not let
anyone sign on as EUGENE,CLERK.AP, because he doesn't have a profile in the
database.

Thus, by adding those five users using RUN MAIN.PUB.VESOFT,ADD and by inserting
a $VEPROFILE @.AP line into SECURCON.DATA.VESOFT, we've accomplished two
things:

   * Indicated that only JOE,CLERK.AP, PETE,CLERK.AP, MARY,CLERK.AP,
     MELINDA,MGR.AP, and JOE,MGR.AP can log on to the AP account (anybody else
     would be denied access).

   * Specified a different password for each of these users (even though they
     share the same MPE user IDs).

Of course, we would typically configure not five, but fifty or five hundred
users; however, this is a good example of using SECURITY to implement session
name security.  Also, it demonstrates the concept of the SECURITY user profile,
which is useful for much more than just session name security -- more about
that shortly.

LOGON MENUS


Menus: general discussion
Denying users access to MPE
Logon menus

There is usually no reason for a non-programmer user to have access to the
Command Interpreter (at the MPE prompt).  Take your average accounting clerk --
you might want to give him the power to run your Accounts Payable system, your
Accounts Receivable system, and an Electronic Mail system.  You don't want him
to be able to do anything else -- run programs, edit files or do other things
like that.  There is a fixed, well-defined set of things that he may do.

The best way of supporting this sort of user is to give him a SECURITY logon
menu.  Instead of being dropped down to the MPE prompt after he logs on (and
inputs his SECURITY passwords), he'll see a menu of the things he's allowed to
do and will be asked to select one of those things.  For instance, a typical
menu session might look like:

   :HELLO JOE,CLERK.ACCTNG
                    .  .  .
   PLEASE ENTER THE SECURITY PASSWORD:    << echo is off >>

   Welcome!  You are now signed on.

   ACCOUNTING CLERK MENU:

     1.  RUN ACCOUNTS PAYABLE SYSTEM
     2.  RUN ACCOUNTS RECEIVABLE SYSTEM
     3.  RUN GENERAL LEDGER SYSTEM
     4.  SEND/RECEIVE ELECTRONIC MAIL
     5.  CHANGE YOUR OWN PASSWORD

   Enter selection (or E to EXIT, R to REDISPLAY or L to LOCKUP):

At this point, the user can enter any of the listed options (1 through 5), type
E to exit the menu and log off the system, or type L to LOCKUP his terminal
until he re-enters his passwords (see "Allowing A User To Lock Up His Terminal
Before Leaving It Unattended" for details on LOCKUP).  Again, note that the
listed options are the only things that he can execute; he can't type arbitrary
MPE commands, look at or modify arbitrary files, etc.  This is both more secure
and more convenient than giving him full Command Interpreter access.

The name of a menu file is part of a user's SECURITY user profile (together
with the user ID, account name, session name [discussed above], SECURITY
password(s), and terminal/day-of-week/time-of-day restrictions).  It can be set
up by (as shown earlier) a
   :RUN MAIN.PUB.VESOFT,ADD

at which point SECURITY will prompt you for all the relevant user information:

   SECURITY/ADD 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: CLERK
   Enter account: ACCTNG
   Enter session name: JOE
   Enter user's real name: JOE TIMOTHY
   Enter permitted terminal numbers:     << hit [RETURN] >>
   Enter day-of-week access restrictions:     << hit [RETURN] >>
   Enter time-of-day access restrictions:     << hit [RETURN] >>

   Enter the menu file name: CLRKMENU.DATA.ACCTNG

   Enter Y if the user is to have SECURITY passwords;
         N if the user is not to have SECURITY passwords;
         A if the user is to have passwords, but should enter the
           correct passwords himself the first time he logs on.
   Your selection (Y/N/A)? Y

   PLEASE ENTER THE SECURITY PASSWORD:     << Joe enters it, no echo >>

Now, whenever JOE,CLERK.ACCTNG logs on, he'll automatically see the menu
specified in the menu file CLRKMENU.DATA.ACCTNG and be able to execute the
options indicated in that file.  Naturally, different users can easily have
different menu files (for instance, one for the typical CLERK.ACCTNG user, a
special one for MARY,CLERK.ACCTNG, another for MGR.ACCTNG users, and so on).
Note that

   Like all SECURITY user profile-related features (including session name
   security, SECURITY passwords, terminal/day-of-week/time-of-day access
   restrictions, etc.) logon menu files only take effect for those users for
   whom the $VEPROFILE option is enabled in the SECURCON.DATA.VESOFT
   configuration file.

In other words, if all ACCTNG users are supposed to have SECURITY user
profiles, it's not enough just to add these profiles to the database -- you
must also have a line in SECURCON.DATA.VESOFT that looks like

   $VEPROFILE @.ACCTNG                 or

   $VEPROFILE @.TEST @.ACCTNG @.PROD   or better

   $VEPROFILE @.@

-- any userset that includes all users in the ACCTNG account.  For more
information on this, see the "Session Name Security" chapter above.

The menu file, of course, has to define all the options available to this user.
CLRKMENU.DATA.ACCTNG might, for instance, look like this:

   *HEADER ACCOUNTING CLERK MENU:
   *HEADER
   *CAPTION    RUN ACCOUNTS PAYABLE SYSTEM
      FILE APBASE=APBASE.DATA.AP
      RUN AP000.PUB.AP;LIB=P;NOCB
   *CAPTION    RUN ACCOUNTS RECEIVABLE SYSTEM
      FILE ARBASE=ARBASE.DATA.AP
      RUN AR000.PUB.AP;PARM=?$CINTEGER$What option number do you want?
   *CAPTION    RUN GENERAL LEDGER SYSTEM
      FILE XXFILE=XXDATA.PROD.GL
      GLUDC
   *CAPTION    SEND/RECEIVE ELECTRONIC MAIL
      RUN MAILSYS.PUB.MAIL
   *CAPTION    CHANGE YOUR OWN PASSWORD
      RUN MAIN.PUB.VESOFT,VEPASSWORD

As you can see, menu files have a special format of their own; for more
information on actually setting up a menu file, see the "Logon Menus Revisited:
A Detailed Explanation" section below.


MENU-FILE, SECURCON file keyword
$MENU-FILE, SECURCON file keyword
is another -- and possibly better -- way of defining a menu file for a
user (or an entire set of users); just add a $MENU-FILE keyword to the
SECURCON.DATA.VESOFT configuration file.  Thus,

   $MENU-FILE  CLRKMENU.DATA.AP  @.AP-MGR.AP

tells SECURITY that all users in the AP account (except for MGR.AP) are to have
CLRKMENU.DATA.AP as their menu file.  (Note that they will still have to have a
user profile to get logged on and get to this menu; it's just that the user
profile won't have to include the filename).

If you do indeed have a whole userset that needs to use a single menu file,
this can be more convenient and more secure (since it decreases the chance that
users might be accidentally defined without a menu file).

Since there are two places where a menu file can be configured for a user (the
$MENU-FILE and the user profile), we have to determine which one to use.  Our
rules are:

   * If a user was explicitly added with a menu file in his user profile, we
     use the one from his user profile.

   * If a user was added without a menu file in his user profile, we use the
     one (if any) from $MENU-FILE.

   * If a user was explicitly added with menu file "NONE" in his user profile,
     we will ignore any applicable $MENU-FILE setting and let him log on
     without a logon menu.

SECURITY PASSWORDS


SECURITY passwords ``contents
SECURITY passwords

In the past few sections, we've mentioned SECURITY passwords -- whenever you
configure a SECURITY user profile, you may have the user enter a SECURITY
password as part of that profile.

Why do we even have SECURITY passwords -- why not stick entirely to MPE
passwords?

   * SECURITY passwords can be imposed on session name + MPE user ID + account
     name rather than on just an MPE user ID and account.  A single user ID
     (USER.PAYROLL) may be used by 50 different people, each with his own
     session name and his own password.  Clearly, we couldn't just use MPE
     passwords for this.  (Note, however, that you need not impose SECURITY
     passwords on a session name basis if you don't want to; you can set them
     up on an MPE user ID basis as well.)

   * SECURITY passwords are one-way encrypted.  They're not readable (even to
     privileged or SM users or people looking through your backup tapes) as
     ordinary MPE passwords usually are.

   * SECURITY passwords can contain any typable characters (but note that
     lower-case letters are always UPSHIFTED; e.g.  the password "foobar" is
     the same as the password "FOOBAR").

   * You can set up not just one SECURITY password, but several.  Each user
     would then be prompted for a random one of his passwords at logon time,
     thus adding a certain element of uncertainty -- even if a would-be
     violator figures out one of the user's passwords (e.g.  looks at the
     user's fingers when he's typing it), he has no guarantee that that
     password would be the one that will come up when he tries to log on.

     One particular case of multiple SECURITY passwords that some of our
     customers use is the "personal profile password" system.  This way, a
     user's passwords are various pieces of personal profile information (his
     mother's maiden name, the city his grandfather was born in, the elementary
     school he went to, etc.); when the user is configured, he is prompted for
     all of these "personal profile passwords" -- whenever he logs on, he'll be
     randomly prompted for one of these passwords.

By default, each SECURITY user profile is expected to have one password
(prompted for with "PLEASE ENTER THE SECURITY PASSWORD:").  The system manager
may indicate that there are to be several SECURITY passwords by putting their
prompts into the VEPROMPT.DATA.VESOFT file, e.g.


VEPROMPT.DATA.VESOFT ``prompt`questions
VEPROMPT.DATA.VESOFT
Multiple SECURITY passwords

   :HELLO MANAGER.VESOFT
   :EDITOR
   /ADD
       1     PLEASE ENTER SECURITY PASSWORD A:
       2     PLEASE ENTER SECURITY PASSWORD B:
       3     PLEASE ENTER SECURITY PASSWORD C:
       4     //
   /KEEP VEPROMPT.DATA.VESOFT,UNN;EXIT

When a user is added to the database, he'll be prompted for all three
passwords:

   SECURITY/ADD 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: CLERK
   Enter account: ACCTNG
   Enter session name: JOE
   Enter user's real name: JOE TIMOTHY
   Enter permitted terminal numbers:     << hit [RETURN] >>
   Enter day-of-week access restrictions:     << hit [RETURN] >>
   Enter time-of-day access restrictions:     << hit [RETURN] >>
   Enter the menu file name: CLRKMENU.DATA.ACCTNG
   Enter Y if the user is to have SECURITY passwords;
         N if the user is not to have SECURITY passwords;
         A if the user is to have passwords, but should enter the
           correct passwords himself the first time he logs on.
   Your selection (Y/N/A)? Y

   PLEASE ENTER SECURITY PASSWORD A:     << have the user type his password >>
   Please enter the answer again:        << twice, for verification >>
   PLEASE ENTER SECURITY PASSWORD B:
   Please enter the answer again:
   PLEASE ENTER SECURITY PASSWORD C:
   Please enter the answer again:
   *** User has been added ***

Then, whenever the user logs on, he'll be prompted for a random one of his
passwords, and will have to enter that password to log on; for example:

   :HELLO JOE,CLERK.ACCTNG
                    .  .  .
   PLEASE ENTER SECURITY PASSWORD B:     << enter it, no echo >>
   Error: Incorrect password.
   PLEASE ENTER SECURITY PASSWORD B:     << enter it again >>
   Welcome!  You are now signed on.


Personal profile passwords
of the ways in which multiple passwords might be used by SECURITY users is
the "personal profile password" approach.  This way, the system manager sets up
a VEPROMPT.DATA.VESOFT file that looks something like this:

       1     WHAT IS YOUR MOTHER'S MAIDEN NAME?
       2     WHAT CITY WAS YOUR GRANDFATHER BORN IN?
       3     WHAT WAS THE NAME OF YOUR FIRST LOVE?

When the user is set up, he'll have to answer all these questions (note that
although the :RUN MAIN.PUB.VESOFT,ADD and the entry of most user information
should be by an account or system manager, it's a good idea for the user to
enter the passwords himself, thus keeping them as private as possible).  The
advantage of having personal questions like these is that the user will have no
trouble remembering them, and might be less likely to reveal them (as private
information) to other people who just want to "borrow" his user ID.  Banks
often use this system to provide an "electronic fingerprint" based upon a
user's personal data.

As we mentioned before, this is just one possible configuration -- you can have
several non-personal passwords (password A, password B, password C) or just one
SECURITY password (as is the default configuration).  SECURITY is flexible
enough to fit any approach.

In fact, you might prefer to let different users have different sets of
password prompts -- for instance, some may have only one SECURITY password,
while others have several personal profile passwords.  To do this, you can use
the $VEPASS-PROMPT-FILE keyword:


VEPASS-PROMPT-FILE, SECURCON file keyword ``prompt`password
$VEPASS-PROMPT-FILE, SECURCON file keyword
Multiple sets of password prompts using $VEPASS-PROMPT-FILE
Prompts for SECURITY passwords

   $VEPASS-PROMPT-FILE "PPROMPT.DATA.VESOFT" @.AP @.GL
   $VEPASS-PROMPT-FILE "PROMPT1.DATA.VESOFT" @.@-@.AP-@.GL

This indicates that AP and GL account users are prompted for passwords using
the prompts listed in the PPROMPT.DATA.VESOFT file, whereas all other users use
the PROMPT1.DATA.VESOFT file.


VEPASS-PROMPT, SECURCON file keyword ``prompt`password
$VEPASS-PROMPT, SECURCON file keyword
you use only one SECURITY password prompt, you can actually specify it
directly in the SECURCON.DATA.VESOFT file using the $VEPASS-PROMPT keyword:

   $VEPASS-PROMPT "ENTER SECURITY USER PASSWORD: " @.AP @.GL

The advantage of using this keyword (rather than using $VEPASS-PROMPT-FILE) is
that SECURITY won't have to open another file when the user logs on -- each
file open takes time.  In fact, if you want to have the same single prompt for
all users in the system, you might just say

   $VEPASS-PROMPT "ENTER SECURITY USER PASSWORD: "

This will override any prompts you have in the VEPROMPT.DATA.VESOFT file.

Note, however, that the only difference between setting a single password
prompt with $VEPASS-PROMPT and setting it with a $VEPASS-PROMPT-FILE that
points to a single-record file is logon speed.  Otherwise, SECURITY doesn't
care if the password prompt came from a $VEPASS-PROMPT keyword or from a prompt
file.


VE-NUM-PROMPTS, SECURCON file keyword ``number`prompts
$VE-NUM-PROMPTS, SECURCON file keyword
you'd like, you can actually have the user prompted for more than one
password -- you might, for instance, have him prompted for a random three out
of five questions, and permit him to log on only if he answers all three of
them correctly.  You can specify this by adding a $VE-NUM-PROMPTS line to the
SECURCON.DATA.VESOFT file, e.g.

   $VE-NUM-PROMPTS 3 @.AP

This specifies that all users in the AP account should be asked for a random
three of their passwords every time they log on; if they answer even one of
them incorrectly, they will be denied access.


Deleting SECURITY password prompts
DELETED, used in the VEPROMPT file to delete prompts
that if you want to delete a password prompt in the VEPROMPT file, you
can't just use an EDITOR's /DELETE command (otherwise the relative positions in
the file of the other password prompts will change).  Instead, you should
/REPLACE the line with the string "DELETED":

   :HELLO MANAGER.VESOFT
   :EDITOR
   /TEXT VEPROMPT; LIST ALL
       1     PLEASE ENTER SECURITY PASSWORD A:
       2     PLEASE ENTER SECURITY PASSWORD B:
       3     PLEASE ENTER SECURITY PASSWORD C:
   /REPLACE 2
       2     PLEASE ENTER SECURITY PASSWORD B:
       2     DELETED
   /KEEP VEPROMPT.DATA.VESOFT,UNN; EXIT

This will prevent SECURITY from asking for password B.


VE-TIMEOUT, SECURCON file keyword ``timeout
$VE-TIMEOUT, SECURCON file keyword
default, a user has only 120 seconds (2 minutes) to input his SECURITY
password at logon time; if he doesn't, he'll be logged off.  You can increase
or decrease this time by adding to the SECURCON.DATA.VESOFT configuration file
the keyword

   $VE-TIMEOUT numseconds [usersets]

e.g.

   $VE-TIMEOUT 300

You can also specify a numseconds of 0 (e.g.  $VE-TIMEOUT 0 @.AP) to turn off
the timeout altogether.


VE-NUM-TRIES, SECURCON file keyword
$VE-NUM-TRIES, SECURCON file keyword
, SECURITY gives the user two chances to correctly enter his password
before logging him off.  If you like, you can change this number by adding

   $VE-NUM-TRIES number [usersets]

to your SECURCON.DATA.VESOFT configuration file.

TERMINAL, TIME-OF-DAY, AND DAY-OF-WEEK RESTRICTIONS


Terminal restrictions ``contents
Terminal restrictions
Day-of-week restrictions
Time-of-day restrictions

Often, certain access attempts (even when the correct passwords are specified)
are in and of themselves security violations.

For instance, say that one of your payroll clerks tries to log on -- on
Saturday at midnight from a dial-in line! Even if he can specify the right
passwords, this isn't a good thing -- there's nobody there to supervise him and
make sure he's indeed authorized to use the system.

Similarly, a console operator has no business running the accounts payable
system from one of the computer room terminals; it's much better to require
that all A/P users use the terminals in the accounting area, where the presence
of unauthorized people would be noticed.

When you add a user -- :RUN MAIN.PUB.VESOFT,ADD -- you can specify:

   * Which terminals the user may log on to (or which ones he may not log on
     to);

   * What days of week the user may log on;

   * And, what times of day the user may log on.

For instance, you may say:

   :RUN MAIN.PUB.VESOFT,ADD

   SECURITY/ADD 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: CLERK
   Enter account: ACCTNG
   Enter session name: JOE
   Enter user's real name: JOE TIMOTHY

   Enter permitted terminal numbers: 71,72,73,74,77
   Enter day-of-week access restrictions: MON-FRI
   Enter time-of-day access restrictions: 9 AM-6 PM

   Enter the menu file name: CLRKMENU.DATA.ACCTNG
   Enter Y if the user is to have SECURITY passwords;
         N if the user is not to have SECURITY passwords;
         A if the user is to have passwords, but should enter the
           correct passwords himself the first time he logs on.
   Your selection (Y/N/A)? Y

   PLEASE ENTER THE SECURITY PASSWORD:

You've just specified that the user JOE,CLERK.ACCTNG may only log on to
terminals 71, 72, 73, 74 and 77, only MONday through FRIday, and only from 9 AM
to 6 PM.  All other logon attempts would be rejected even without any SECURITY
password prompts.

If you wanted to, you might have said, in response to the "Enter permitted
terminal numbers:" prompt:

   Enter permitted terminal numbers: NOT 20, 61, 62

This would allow JOE,CLERK.ACCTNG logons from any terminal other than 20, 61 or
62 (which might be the console and the dial-in lines).

You may, of course, just hit [RETURN] in response to all three prompts and
allow access on all terminals, all days of week, and all times of day (also,
you naturally can specify some restrictions but not others).  However,
terminal/day-of-week/time-of-day restrictions can be quite useful for
forbidding dial-in access, restricting access to only terminals in a certain
area, forbidding off-hours logons, etc.

LETTING A USER SPECIFY HIS OWN SECURITY PASSWORDS WHEN HE FIRST LOGS ON


Letting a user specify his own SECURITY passwords ``contents
Letting a user specify his own SECURITY passwords
SECURITY passwords: inputting them

There are two kinds of information in a user profile: on the one hand, the
user's session name, user ID, account name, restrictions, and menu file, and on
the other hand, the user's password.

The first set of things should clearly be specified by the manager (you don't
want a user setting up his own terminal, day-of-week or time-of-day
restrictions or even his own menu file); however, it's not a good idea for the
manager to enter passwords for the user -- the user should enter his own
passwords himself.

There are several ways of doing this:

   * you can call a user over to the manager's terminal when he's being added
     and let him type in the passwords himself;

   * you can have the manager specify some dummy initial passwords and then
     have the user use the RUN MAIN.PUB.VESOFT,VEPASSWORD option (see "Changing
     User Profiles" below) to change the passwords to the correct ones.

However, SECURITY provides yet another alternative which many users find
appealing.  When a manager adds a user profile, RUN MAIN.PUB.VESOFT,ADD will
ask him whether or not the user is to have SECURITY passwords -- in response to
this, the manager may enter "A":

   SECURITY/ADD 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: CLERK
   Enter account: ACCTNG
   Enter session name: JOE
   Enter user's real name: JOE TIMOTHY
   Enter permitted terminal numbers: NOT 20,61,62
   Enter day-of-week access restrictions: MON-FRI
   Enter time-of-day access restrictions: 9 AM-6 PM
   Enter the menu file name: CLRKMENU.DATA.ACCTNG
   Enter Y if the user is to have SECURITY passwords;
         N if the user is not to have SECURITY passwords;
         A if the user is to have passwords, but should enter the
           correct passwords himself the first time he logs on.
   Your selection (Y/N/A)? A
   ENTER THE TEMPORARY SECURITY PASSWORD:   <<you say "TEMPPASS">>
   *** User has been added.  ***

As you see, SECURITY didn't ask the manager what the user's passwords are going
to be -- rather, it asks for a single temporary password (let's say that in
this case the manager specifies "TEMPPASS").  Then, the first time that the
user logs on, he'll be prompted first for the temporary password (which he must
enter correctly or he'll be denied access) and then for the correct values of
his normal password:

   :HELLO JOE,CLERK.ACCTNG
                    .  .  .
   ENTER THE TEMPORARY SECURITY PASSWORD:   <<user must say "TEMPPASS">>
   Please enter your new SECURITY passwords now:
   PLEASE ENTER THE SECURITY PASSWORD:  << Joe enters it, no echo >>
   Please enter the answer again:
   Welcome!  You are now signed on.

After that, it will be just as if the user had specified the passwords at user
configuration time -- the password will be asked at logon time and checked
against the correct password(s).  However, as you see, the correct password(s)
were specified not by the account/system manager at user configuration time,
but by the user himself the first time he logged on.

The main advantage of this approach is that it's a lot easier for the person
doing the configuring -- a manager can set up fifty profiles in minutes,
without having to call each user over to enter passwords.  This can make
initial user configuration a breeze.  And, since the user is never left without
a password (he first has the temporary one and then the real ones that he
himself enters), there's no danger to your system security.


VEPASS-TEMP-PROMPT, SECURCON file keyword ``temporary`passwords
$VEPASS-TEMP-PROMPT, SECURCON file keyword
, if you want to change the default temporary password prompt (which
is "PLEASE ENTER THE SECURITY TEMPORARY PASSWORD:"), you can do so -- just
specify (in your SECURCON.DATA.VESOFT file) a line such as:

   $VEPASS-TEMP-PROMPT "WHAT IS THE ONE-TIME PASSWORD: " @.PROD

This means that the temporary password prompt issued for all users in the PROD
account (@.PROD) will be "WHAT IS THE ONE-TIME PASSWORD: ".

Finally, if you really want to, you can disable the temporary passwords
altogether by saying

   $VEPASS-TEMP-PROMPT "" [usersets]

If you do this, then any user added with the "A" option (i.e.  so that he
specifies his own passwords when he first logs on) will be initially set up
without any passwords.  He will be allowed to set up his new passwords when he
first logs on, but that first logon will not be SECURITY-password-protected at
all.  We do not recommend using this feature; however, we provide it to
maintain compatibility with an older version of SECURITY.

SECURITY PROFILES THAT SPAN MULTIPLE MPE USER IDs (e.g.  JOE,@.@)


SECURITY profiles that span multiple MPE user IDs ``contents
SECURITY profiles that span multiple MPE user IDs

SECURITY user profiles are imposed for a particular session name, user ID and
account name.  What if you don't care about session names? What if you want a
user to be able to log on as "JACK.DEV" with any session name he pleases? (We
don't recommend this approach, though...)


Session names, not using them
is flexible enough to allow you to do this.  When doing RUN
MAIN.PUB.VESOFT,ADD specify an "@" in place of the session name:

   SECURITY/ADD 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: JACK
   Enter account: DEV
   Enter session name: @
   ...

This means that any user logging on as JACK.DEV, regardless of his session
name, will match this user profile and be asked this profile's SECURITY
passwords, see this profile's menu (if any), be restricted by this profile's
terminal/day-of-week/time-of-day restrictions (if any), etc.

But, wait -- there's more! Actually, you can specify an "@" not just in the
session name field, but also in the user ID or account field (or any
combination of the three).  Why would you want to do this? Well, let's say that
you want to allow your system manager (let's say her name is ANNE) to log on to
any user ID in the system (perhaps for troubleshooting purposes).  With
SECURITY, she can give herself one set of passwords that will allow her to log
on anywhere.  She can just say:

   SECURITY/ADD 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: @
   Enter account: @
   Enter session name: ANNE
   ...

Whenever SECURITY sees any logon with session name ANNE to any valid MPE user
ID, SECURITY will use this user profile and expect the SECURITY passwords
specified within it.  This way -- without having to somehow figure out the
user's passwords, which are one-way encrypted and undecipherable -- the system
manager can log on as any user in the system.

Similarly, you can specify "@"s just in the user ID field, just in the account
field, etc.  For instance, setting up a user profile such as:

   SECURITY/ADD 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: JACK
   Enter account: @
   Enter session name: @
   ...

will set up one set of SECURITY passwords (or, of course, one single SECURITY
password, if you don't use the multiple passwords feature) that will apply to
users named JACK in all accounts in which they are configured (i.e.  @,JACK.@).

So if you have users JACK.DEV, JACK.PROD, and JACK.AP (presumably all referring
to the same Jack) and you don't want to add identical user profiles for each of
them, setting up one profile for JACK.@ would be just the thing.  Of course,
this user can still only log on to those accounts which actually have a JACK
user ID -- if you don't have a JACK.SYS user ID, he won't be able to log on
that way.

Naturally, this is a powerful feature and must be used wisely.  Any SECURITY
user profile that allows access to all users in all accounts (such as
"ANNE,@.@") must have its passwords kept very secret, since it can be used to
log on to MANAGER.SYS and any other user ID.  However, this feature can be a
very useful tool in your system management and security administration.

An interesting question that arises with "@" wildcards is: what if there are
two or more user profiles that could conceivably apply to a particular logon.
For instance, say that I log on as "EUGENE,TEST.DEV", and there is a SECURITY
user profile for "EUGENE,@.@", for "TEST.DEV", and for "EUGENE,@.DEV" -- which
one will apply to my logon? Well, SECURITY has chosen (mostly arbitrarily) the
following hierarchy:

   EUGENE,TEST.DEV        is searched for first; if it isn't found,
   @     ,TEST.DEV        is then looked for; after that,
   EUGENE,@   .DEV        then
   @     ,@   .DEV        then
   EUGENE,TEST.@          then
   @     ,TEST.@          then
   EUGENE,@   .@          then
   @     ,@   .@

If none of the above entries is found, SECURITY will forbid the logon
altogether; otherwise, it'll use the first profile found on the above list.  A
good general rule to keep in mind is that it always chooses the more specific
before the less specific -- if I'm logging on as EUGENE,TEST.DEV, then an exact
match "EUGENE,TEST.DEV" takes precedence over the less specific "EUGENE,@.DEV"
and the even less specific "EUGENE,@.@".

An important thing to remember is that hitting return when prompted for the
session name is not the same as specifying a session name of "@".  A user
profile with user JACK, account DEV, and a blank session name specifically
refers to the user JACK.DEV logging on with no session name -- if it was
entered with session name "@", it would refer to JACK.DEV logging on with any
session name.

CONFIGURING PROFILES TO SHARE (INHERIT) PASSWORDS

(WHAT IF THE SAME PERSON MUST LOG ON TO DIFFERENT MPE USER IDs?


Configuring profiles to share (inherit) passwords ``contents
Configuring profiles to share (inherit) passwords
Password sharing
Parent user profiles
Inheriting user profiles

Often you may want to grant one person access to several MPE user IDs -- for
instance, HELEN,CLERK.PAYROLL, and HELEN,USER.GL.  You could, of course, add
her twice to the database, once for each session name/user id/account name
combination; however, not only is that harder to initially set up, but it's
also a bother to maintain -- if, for instance, she changes her passwords (e.g.
when they automatically expire), she'll have to remember to change them for
both users or face a good deal of confusion.

One thing that you can do in this case is, of course, use the "@" feature to
configure a single user ID "HELEN,@.@" that will then be able to log on to all
users and all accounts in the system (see "Security Profiles That Span Multiple
User IDs" above).  This is applicable in some cases, but can be too broad
(since HELEN would be able to log on as any user in the system, including
HELEN,MANAGER.SYS).  Additionally, this restricts her to only be able to log on
with session name HELEN -- what if you want her to log on as HELEN.AP or
HSMYTHE,USER.HPOFFICE?

To solve this problem, SECURITY lets you define a user profile and say that
this profile inherits the SECURITY passwords from some other user.  For
instance, you might first configure the user profile HELEN,CLERK.PAYROLL:

   SECURITY/ADD 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: CLERK
   Enter account: PAYROLL
   Enter session name: HELEN
   Enter user's real name: HELEN SMYTHE
   Enter permitted terminal numbers: 31,32,33,35,37
   Enter day-of-week access restrictions: MON-FRI
   Enter time-of-day access restrictions: 8 AM-6 PM
   Enter the menu file name: MENU3.PUB.PAYROLL
   Enter Y if the user is to have SECURITY passwords;
         N if the user is not to have SECURITY passwords;
         A if the user is to have passwords, but should enter the
           correct passwords himself the first time he logs on.
   Your selection (Y/N/A)? Y

   PLEASE ENTER SECURITY PASSWORD:
   *** User has been added ***

and then set up the user HELEN,USER.GL as a user ID that INHERITS the SECURITY
password of HELEN,CLERK.PAYROLL:

   SECURITY/ADD 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: USER
   Enter account: GL
   Enter session name: HELEN
   Enter user's real name: =HELEN,CLERK.PAYROLL
   Enter permitted terminal numbers: 45,46,47
   Enter day-of-week access restrictions: MON-SAT
   Enter time-of-day access restrictions: 9 AM-7 PM
   Enter the menu file name: GLMENU.DATA.GL
   *** User has been added ***

Note that in place of the user's real name, we specified an "=" followed by the
session,user.account from which the SECURITY password is to be inherited (if we
were inheriting from HELEN,TEST.DEV, we'd specify a user's real name of
"=HELEN,TEST.DEV").

What information is inherited from a parent record and what isn't? Well, the
inherited things are:

   * The SECURITY passwords, and

   * The real user name (used in log file listings, etc.).

The following items are not inherited, but rather specified explicitly in both
the parent and the inheriting record.

   * Permitted terminal numbers,

   * Day-of-week access restrictions,

   * Time-of-day access restrictions, and

   * Menu file name

This distinction exists because one very often wants to have different
terminal, day-of-week or time-of-day access restrictions, and especially
different menu files for different logon IDs.  (For instance, the payroll
department might very well work on different terminals and keep different
business hours than the AP department; the payroll menu and the AP menu should
probably be quite different.)

The original user profile -- the one specified after the "=" -- is called the
parent user profile (in this case, HELEN,CLERK.PAYROLL); the one that refers to
the parent user profile (HELEN,USER.GL) is called the inheriting user profile.
Of course, you can have several inheriting user profiles that inherit from one
parent -- you might configure HELEN,USER.GL, HELEN.AP, and
HSMYTHE,USER.HPOFFICE to all inherit from HELEN,CLERK.PAYROLL.

Note that when a parent user profile is deleted using the RUN
MAIN.PUB.VESOFT,DELETE option (which we'll discuss shortly), all of its
inheriting user IDs are deleted as well.

USING USER PROFILES WITHOUT SECURITY PASSWORDS


Using user profiles without SECURITY passwords ``contents
Using user profiles without SECURITY passwords

Sometimes, you may choose to only use MPE passwords, and not implement SECURITY
passwords at all (e.g.  if you're not using session names, if you don't care
about password encryption, etc.).  However, you will still probably want to use
the other features of SECURITY user profiles (menu files, terminal
restrictions, day-of-week restrictions, and time-of-day restrictions).

This is very easy to do: when you're adding a user, just enter "N" when
prompted for the SECURITY password "Y"/"N"/"A" flag.

CHANGING USER PROFILES


Changing user profiles ``contents
Changing user profiles
CHANGE, MAIN.PUB.VESOFT entry point

As you may have guessed, any SECURITY user profile that you can add doing RUN
MAIN.PUB.VESOFT,ADD can also be altered using RUN MAIN.PUB.VESOFT,CHANGE.  For
example:

   :RUN MAIN.PUB.VESOFT,CHANGE

   SECURITY/CHANGE 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: SASHA
   Enter account: VESOFT
   Enter session name:    << hit [RETURN] for blank session name >>

     R: Redisplay this menu
     U: User info (user, account, session)
     N: User's real name (now SASHA VOLOKH)
     T: Permitted terminal numbers (now 31 32 33 37)
     D: Permitted logon days of week (now MON-FRI)
     H: Permitted logon time of day (now 9 AM-6 PM)
     M: Menu file name (now NONE)
     A: Ask SECURITY passwords? (now Y = YES)
     @: Change all SECURITY passwords (last changed 88/07/24)
     1: ENTER YOUR SECURITY PASSWORD:
   Which item do you want to change?

As you see, you get a menu that displays the current settings of all the user
parameters (which were initially specified using MAIN.PUB.VESOFT,ADD), and lets
you change one or more of them.  For instance, you might say:

   Which item do you want to change? T

and then be allowed to change the permitted terminals:

   Enter permitted terminal numbers: 31,32,33,37,38

SECURITY will keep asking you "Which item do you want to change?" until you hit
[RETURN], at which point the user profile will be changed and you'll be
prompted for a new user ID, account name, and session name to be changed.

Note that there's an important difference between CHANGE mode and ADD mode:

   * When you add a user and hit [RETURN] in response to terminal, day-of-week
     or time-of-day restrictions, SECURITY assumes no restrictions exist; when
     you add a user and hit [RETURN] in response to user's real name or menu
     file, SECURITY uses a blank name or assumes the user has no menu file.

   * However, when you're changing a user, hitting return in response to the
     user's real name, restrictions or menu file prompt will cause that option
     to be unchanged.  If you want to set the user name to blank, type user
     name "NONE"; if you want to remove a user's menu file (and let him access
     MPE directly), type "NONE" when prompted for the menu file; if you want to
     remove a user's terminal/day-of-week/time-of-day access restrictions (and
     let him log onto all terminals, all days of the week or all times of the
     day), type "ALL" when prompted for the restriction.

This option is, of course, available only to system managers and account
managers working in their own accounts, unless you've explicitly allowed (using
the $MAINT-PERMIT option, documented below) other users to do CHANGEs.

DELETING USER PROFILES


Deleting user profiles ``contents
Deleting user profiles
DELETE, MAIN.PUB.VESOFT entry point

Deleting a user profile is very simple.  Just say:

   :RUN MAIN.PUB.VESOFT,DELETE

   SECURITY/CHANGE 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: TEST
   Enter account: VESOFT
   Enter session name: SASHA
   *** User has been deleted.  ***

and the user will be deleted.

The only other thing you need to know is that if you're deleting a parent user
profile (see above), all its inheriting profiles will be deleted, too -- if
SASHA,CLERK.PAYROLL and SASHA,PROG.DEV inherit their SECURITY passwords from
SASHA,TEST.VESOFT, they'll be deleted together with SASHA,TEST.VESOFT.

LISTING USER PROFILES


Listing user profiles ``contents
Listing user profiles
LISTUSER, MAIN.PUB.VESOFT entry point

Naturally, once you've added a couple of hundred SECURITY user profiles, you'd
want to be able to list them out.  Of course you can't list their passwords
(remember, SECURITY passwords are one-way encrypted), but you'd like to see who
they are, what their session names are, their real names, their restrictions,
their menu files, etc.  SECURITY naturally lets you do this.

What you do is say:

   :RUN MAIN.PUB.VESOFT,LISTUSER

   SECURITY/LISTUSER 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter selection criteria (CR to print all, ? for help):    << hit CR >>
   Listing to (L)ine printer or (T)erminal? T

SECURITY will now pause for a while (it has to sort the user IDs) and will
output a report that looks something like this:

   VESOFT SECURITY USER PROFILE LISTING ON FRI, 20 NOV 1988

                               ASK SECURITY PASSWORDS?
   ACCOUNT  USER     SESSION   V   --DAYS--  ---TIME----  MENU FILE
                                   TERMINALS (OR NOTHING IF ALL ALLOWED)
   @        @        EUGENE    Y   ALL       ALL
   AP       CLERK    SASHA     Y   MON-FRI   10 AM- 6 PM  APMENU.PUB.AP
                                   31 32 33 37
   AR       CLERK    SASHA         MON-SAT   ALL          AR3.DATA.AR
                                   NOT 20 61 62
                               *** FATHER PROFILE: SASHA,CLERK.AP
   ...

As you see, every user has his vital information output in this report.  For
space reasons, when you select (T)erminal output, we will not output the user's
real name, last logon date or last SECURITY password change date -- if you
select (L)ine printer output, we will output these things (in
132-column-per-line format).

Of course, with hundreds of users, this report can get rather cumbersome.  That
is why SECURITY also prompts you to "Enter selection criteria:".  If you hit
[RETURN] and you have SM capability, all users will be listed; if you hit
carriage return and you have AM but not SM, only users in your account will be
listed.  However, you may also specify arbitrary selection criteria indicating
which user profiles you want to list.

The "selection criteria" is a logical expression which returns TRUE to indicate
that the profile should be listed.  This expression can make use of the special
"USER PROFILE attribute variables and functions" listed below.  These variables
are also usable in the SECURCON file for the $FORBID, $VEPASS-FORBID,
$USER-FIELD-FORBID, $LOGON-EXECUTE, and $VIOLATION-EXECUTE keywords as well as
$SEC command selection conditions.  In menu files, you can use the expression
syntax of USERPROFILE.attribute or ![USERPROFILE.attribute].  Finally, if you
own MPEX, you can use the VEPROFILE(...).attribute function in a command file
or other expression.  Please see the Appendix for details on the syntax of this
function.

USER PROFILE ATTRIBUTE VARIABLES AND FUNCTIONS


SECURITY User profile attributes ``contents`news
SECURITY User profile attributes


SECURITY User Profile Attribute Variables and Functions
ACCOUNT, User Profile attribute variable
            [STR]     The account name.


USER, User Profile attribute variable
               [STR]     The user name.


SESSION, User Profile attribute variable
            [STR]     The job/session name.


PARENTKEY, User Profile attribute variable ``key`inheriting
PARENTKEY, User Profile attribute variable
          [STR]     The parent profile's account, user, and session
                              names concatenated together (each is blank-filled
                              to 8 characters).  If this is not an "inheriting"
                              profile, the entire field will be blank.


ISINHERITING, User Profile attribute variable ``inheriting
ISINHERITING, User Profile attribute variable
       [BOOL]    TRUE if this is an "inheriting" profile.


NAME, User Profile attribute variable ``real
NAME, User Profile attribute variable
               [STR]     The user's real name (from the parent profile if
                              this is an inheriting user).


TERMALLOW, User Profile attribute variable ``allowed
TERMALLOW, User Profile attribute variable
          [BOOL]    TRUE if the TERMINALS array indicates on which
                              terminals the user may log on.


TERMDISALLOW, User Profile attribute variable ``disallowed
TERMDISALLOW, User Profile attribute variable
       [BOOL]    TRUE if the TERMINALS array indicates on which
                              terminals the user may not log on.


TERMINALS, User Profile attribute variable ``allowed
TERMINALS, User Profile attribute variable
          [INT]     (ARRAY) The array of terminals on which the user
                              can or cannot (depending on the
                              TERMALLOW/TERMDISALLOW setting) log on; up to 30
                              elements, terminated by a 0; if there are no
                              terminal restrictions, then element TERMINALS[0]
                              is 0.


TERMINALALLOWED, User Profile attribute variable ``allowed
TERMINALALLOWED, User Profile attribute variable
(I)
                    [BOOL]    TRUE if user is allowed to use LDEV# I.


DAYBEGIN, User Profile attribute variable
           [INT]     The first day of the week on which the user may
                              log on (0=Sunday, 6=Saturday).


DAYEND, User Profile attribute variable
             [INT]     The last day of the week on which the user may
                              log on (0=Sunday, 6=Saturday).


HOURBEGIN, User Profile attribute variable
          [INT]     The first hour of the day in which the user may
                              log on (0 to 23).


HOUREND, User Profile attribute variable
            [INT]     The last hour of the day in which the user may
                              log on (0 to 23).


MENU, User Profile attribute variable
               [STR]     The name of this user's menu file.  If this is
                              blank or "$MENU-FILE", then the default menu for
                              this user will be used.  If this is "NONE", no
                              menu will be used (even if there is a default).


VEPASSFLAG, User profile attribute variable
         [STR]     A single character showing the status of the
                              profile's password(s).  The following attributes
                              are pre-configured to match the legal values that
                              the flag may contain:


HASVEPASS, User Profile attribute variable
          [BOOL]    TRUE if the user has SECURITY passwords
                              [VEPASSFLAG=Y].


NOVEPASS, User Profile attribute variable
           [BOOL]    TRUE if the user has no SECURITY passwords
                              [VEPASSFLAG=N].


INPUTVEPASS, User Profile attribute variable
        [BOOL]    TRUE if the user is supposed to input his
                              SECURITY passwords next time he logs on
                              [VEPASSFLAG=A].


ASKVEPASS, User Profile attribute variable
          [BOOL]    (Same as INPUTVEPASS).


ISOBSOLETE, User profile attribute variable
         [BOOL]    TRUE if the profile passwords are obsolete
                              [VEPASSFLAG=O].


INVALIDATTEMPTS, User Profile attribute variable``deactivated
INVALIDATTEMPTS, User Profile attribute variable
    [INT]     The number of consecutive invalid logon attempts
                              by this user so far (when this number reaches the
                              configured limit, the user is deactivated); this
                              field will contain 32767 if the user has been
                              deactivated, either because of invalid logon
                              attempts or by the DEACTIVATE command.


LASTLOGONDATE, User Profile attribute variable
      [DATE]    Date the user last logged on.


LASTLOGONTIME, User Profile attribute variable
      [TIME]    Time the user last logged on.


LASTLOGONLDEV, User Profile attribute variable
      [INT]     LDEV the user last logged on to (set to 0 before
                              first logon).


LASTPASSCHGDATE, User Profile attribute variable

                    [DATE]    Date the user's SECURITY passwords were last
                              changed.


UF, User Profile attribute variable ``user`field
UF, User Profile attribute variable
(S)               [STR]     Value of the user field indicated by S.

As you can see, every one of these variables has a "datatype" of INTEGER,
STRING, BOOLEAN, DATE or TIME, which dictates what you can do with it (for
instance, you can't compare an integer with a string).  The various operators
defined on these variables are discussed in greater detail in Appendix;
however, some good examples should be rather obvious:

   Enter selection criteria: ACCOUNT="AP" or ACCOUNT="AR"

     (finds all users in the AP and AR accounts)

   Enter selection criteria: MENU="" or MENU="NONE"

     (finds all users without menu files)

   Enter selection criteria: ACCOUNT<>"DEV" and NOVEPASS

     (finds all users configured without SECURITY passwords, except for those
      in the DEV account)

   Enter selection criteria: ACCOUNT="PROD" and INPUTVEPASS

     (finds all users in the PROD account that were configured with the "A"
      option to input SECURITY passwords at logon but haven't yet logged on)

INDICATING A SYSTEM NAME FOR REPORT HEADINGS


Indicating a system name for report headings ``contents
Indicating a system name for report headings

If you have more than one computer, you'll probably want to have the LISTUSER
(and LISTLOG) printouts indicate which computer they pertain to.  SECURITY lets
you specify your "system name" to be put into your LISTLOG and LISTUSER report
headings.


HPSYSNAME, MPE/iX variable used by SECURITY ``system`name
HPSYSNAME, MPE/iX variable used by SECURITY
SYSNAME.PUB.VESOFT, special :FILE-equation
MPE/V and MPE/iX differences: setting the system name
you're running on an MPE/iX machine, you should just say

   :SETVAR HPSYSNAME "systemname"

(e.g.  :SETVAR HPSYSNAME "SYSALPHA") before running SECURITY; if you're running
on an MPE/V machine (which doesn't have a :SETVAR command), you can either use
the %SETVAR command of MPEX (since MPEX emulates MPE/iX's new commands) or say

   :FILE SYSNAME.PUB.VESOFT=SYSALPHA     << or whatever the name is >>

There doesn't actually have to be a file called SYSALPHA for this to work; the
:FILE-equation is just a way to tell SECURITY what the system name is.  You may
want to put the appropriate :SETVAR or :FILE-equation into your SECURCON.DATA
file ($LOGON-EXECUTE) so that it's automatically executed every time you log
on.  Other VESOFT report-generating products (such as VEAUDIT and MPEX's %LISTF
and %SHOWOUT commands) will then also be able to print the system names in
their report headers.

Note that if you're on MPE/V and use :FILE SYSNAME.PUB.VESOFT=xxx to specify
the system name, MPEX, SECURITY, and VEAUDIT will look at this file equation
once and then (for speed reasons) save the system name in their own special
session-local variable.  This means that once you've set up this
:FILE-equation, you won't be able to change it for the remainder of your
session (although you probably wouldn't even want to).  If you do want to alter
the system name you've set up this way, you should either run MPEX and do a
"%SETVAR HPSYSNAME 'newsysname'" inside it or re-logon and then issue your new
:FILE-equation.

COMMAND-DRIVEN SECURITY MAINTENANCE (%SEC)


Command-driven SECURITY maintenance (%SEC) ``contents`news
Command-driven SECURITY maintenance (%SEC)

In addition to the dialog/menu interface (accessed by running MAIN.PUB.VESOFT
with particular entry points like ADD, CHANGE, DELETE, LISTUSERS, etc.),
SECURITY also has a command-driven interface.  The advantages of this interface
are:

   * Many of the commands let you operate not just on a single user profile but
     on sets of user profiles, so that you can, for example, delete all the
     user profiles which haven't been logged on to in the past 90 days.

   * Adding a number of users is more convenient since the person adding them
     only needs to enter one line of input for each user rather than go through
     the whole dialog.

   * If a site doesn't use certain user profile parameters (e.g.  terminal,
     day-of-week or time-of-day restrictions), a person adding a user profile
     can just ignore those fields rather than be prompted for them and have to
     hit [RETURN] for each one.  This is particularly relevant for future
     extensions of SECURITY -- as we add more fields to a user profile, we
     don't want to burden existing users who don't choose to use those fields.

   * Performing maintenance actions in job mode is much easier.

If you are an MPEX user as well as a SECURITY user, the most convenient way for
you to execute these commands is by saying, from MPEX,

   %SEC cmdname parameters

e.g.

   %SEC ADD JOE,CLERK.AP;NAME=JOE SMITH;MENU=APMENU.DATA.AP

You can also put %SEC commands into MPEX command files.


SEC, MAIN.PUB.VESOFT entry point
you are not an MPEX user, you can either do a

   :RUN MAIN.PUB.VESOFT,SEC;INFO="command"

e.g.

   :RUN MAIN.PUB.VESOFT,SEC;INFO="LISTUSER @.@-@.SYS"

or do a

   :RUN MAIN.PUB.VESOFT,SEC

which will then prompt you with "%SEC " for SECURITY commands, until you type
"EXIT" to exit.  Note that when you use the SEC entry point, you should not
prefix your commands with "%SEC "; commands entered this way can not be
continued on the next line with an "&".

Finally, SEC commands may be executed within menus (see "Logon Menus Revisited:
A Detailed Explanation" in this manual).

%SEC COMMANDS: GENERAL SYNTAX


%SEC Commands: General syntax ``contents
%SEC Commands: General syntax

Most of the "%SEC" commands operate on user profiles or on sets of user
profiles, e.g.

   %SEC DELETE @.AP+@.GL(LASTLOGONDATE<TODAY-120 and LASTLOGONLDEV<>0)

which will delete all user profiles in the AP or GL accounts to which there has
not been a logon in 120 days (LASTLOGONLDEV is 0 before the user logs on for
the first time).  The general syntax of such commands (commands that operate on
sets of user profiles) is:

   %SEC cmd userset [(selectioncondition)]
                    [;NOVERIFY|QUIET] [;parms]

   * "cmd" is any of the commands (ADD, CHANGE, REACTIVATE, etc.) described
     below.

   * The userset is the general userset as described in the Usersets chapter of
     this manual; it can include '+'s, '-'s, '&'s, and parentheses -- anything
     that pertains to the user's logon ID, but not "LDEV=", "CAP=", "DAY=",
     "TIME=", "ONLINE", "BATCH", etc.  (parameters that vary from logon to
     logon).

   * The selectioncondition further qualifies the userset by the contents of
     its user profiles (if the selection condition is omitted, the entire
     userset is processed).  It is a general logical expression, as described
     in the Appendix, but can also contain SECURITY user profile attribute
     variables (which are listed in the "Listing User Profiles" chapter).

   * All of the userset-handling commands (except for LISTUSER) list the
     profiles on which they will operate before anything is done and ask the
     user whether or not to do the operation -- if he enters "N", the operation
     will not be performed.

     The ";NOVERIFY" keyword tells SECURITY to perform the operations without
     this sort of verification; the ";QUIET" keyword is like ";NOVERIFY" but
     also tells SECURITY not to output the names of the user profiles being
     operated on.

     If no wildcards are specified in the userset, the ";QUIET" option will
     automatically be used (on the principle that the operation can only apply
     to one user profile).

   * Each command (ADD, CHANGE, REACTIVATE, etc.) has it's own ";parms", which
     are described in more detail below.


AT, %SEC command keyword ``at`@
$AT, %SEC command keyword

  * When you say "%SEC REACTIVATE @,CLERK.AP", this means "reactivate all user
     profiles that have user ID CLERK and account name AP" (e.g.
     "JOE,CLERK.AP", "MARY,CLERK.AP", etc.).

     To reactivate the single user profile "@,CLERK.AP" (one configured with
     session name "@"), you should say "%SEC REACTIVATE $AT,CLERK.AP" -- "$AT"
     refers to the "@" in the user profile.

     Remember that all the user profiles that will be operated on are output
     first and you are given a chance to abort the operation -- this should
     avoid any unfortunate accidents.

(NEW) ABORTJOB


%SEC ABORTJOB, SECURITY command``schedule`contents`news
%SEC ABORTJOB, SECURITY command

Syntax:   %SEC ABORTJOB #Aschednumber [;NOVERIFY|;QUIET]
                          mpeuserset

Examples: %SEC ABORTJOB #A3
          %SEC ABORTJOB @.SYS;NOVERIFY

Aborts jobs submitted using STREAMX's scheduling feature (see the "Scheduling
STREAMX Jobs To Repeat" section of this manual).  Note that this is not the
same as the MPE/MPEX :ABORTJOB command, it only aborts jobs that were submitted
via the STREAMX SCHEDULER.

The format of a schednumber is #Annn where "nnn" is the schedule number of the
job as shown by using the %SEC SHOWSCHED command.

When using a userset, the program will display all of the jobs that qualify and
prompt for confirmation before aborting any scheduled jobs.  The ;NOVERIFY
keyword will skip this step, and the ;QUIET keyword suppresses all output.

ADD


%SEC ADD ``contents
%SEC ADD
NAME, %SEC ADD keyword
TERMINALS, %SEC ADD keyword
DAYS, %SEC ADD keyword
TIME, %SEC ADD keyword
MENU, %SEC ADD keyword
INHERIT, %SEC ADD keyword
NOPASS, %SEC ADD keyword
ASKPASS, %SEC ADD keyword
VEPASS, %SEC ADD keyword

   %SEC ADD [session,]user.account
            [;NAME=user's real name]
            [;TERMINALS=[NOT] ldev1,ldev2,...,ldevN]
            [;DAYS=dayfrom-dayto]
            [;TIME=timefrom-timeto]
            [;MENU=menufilename]
            [;INHERIT=[parentsession,]parentuser.parentaccount]
            [;NOPASS|ASKPASS]
            [;VEPASS=pass1;VEPASS=pass2;...;VEPASS=passN;]
            [;userfieldname=val]...

   %SEC ADD JOE,@.PROD;NAME=JOE BROWN;TERMINALS=NOT 20,21 &
                      ;DAYS=MON-FRI;TIME=9AM-6PM &
                      ;MENU=MENUF1.DATA.PROD;ASKPASS &
                      ;VEPASS=TEMPPASS

Adds the given user profile (here "JOE,@.PROD" -- note that this is not a
userset, but just a single profile).  The user's real name, terminal,
day-of-week, and time-of-day restrictions, menu file, and the user to inherit
from can be specified in the "%SEC ADD" command.  ";NOPASS", if specified,
indicates that the user is to have no SECURITY passwords; ";ASKPASS" indicates
that the user is to be prompted for his passwords when he first logs on.

Normally, you would do the "%SEC ADD" command, and SECURITY will then prompt
you for your SECURITY password (or passwords); if you specified ";ASKPASS",
SECURITY would prompt you for the temporary password.

If you'd like, you can specify the password on the "%SEC" command itself (after
first making sure that no one is looking over your shoulder) using the
";VEPASS=" keywords -- in the above example, ";ASKPASS" was specified and the
temporary password was given using ";VEPASS=TEMPPASS".

If you've defined any user-defined fields (using the $USER-FIELD keyword -- see
"User-Defined Fields in SECURITY User Profiles" later in this manual), they can
be specified on the "%SEC ADD" command -- for instance, if the fields DEPT and
EXPDATE are defined, you can say

   %SEC ADD JOE,CLERK.PROD;ASKPASS;DEPT=XYZ;EXPDATE=1/1/91

AUTOLOAD


%SEC AUTOLOAD ``contents`load
%SEC AUTOLOAD
$USER, %SEC AUTOLOAD keyword
$ACCOUNT, %SEC AUTOLOAD keyword
$UPASS, %SEC AUTOLOAD keyword

   %SEC AUTOLOAD mpeuserset, [session,][user].[account] ; addparms
                                        [$USER].[$ACCOUNT]

   %SEC AUTOLOAD @.AP, $USER.AP; &
        MENU=APMENU.DATA.AP; ASKPASS; VEPASS=$UPASS

Adds SECURITY profiles that correspond to the MPE users in the given MPE
userset -- in the above example, a user profile is added to the SECURITY
database for each user in the AP account.

The "$USER" means "set the profile's user ID to the MPE user ID"; "$ACCOUNT"
means  "set the profile's account to the MPE account"; "$UPASS" means    "set
the profiles temporary SECURITY password to be his current MPE password".

BACKG


%SEC BACKG ``contents
%SEC BACKG


BACKG TASKS
TASKLIST -- see also %BACKG in the MPEX manual

  %SEC BACKG [SHOW]
              [STARTJOB]
              [STOPJOB]
              [START|STOP, taskname[,...]]

            "taskname" is one (or more) of:
               ALARM   AUDITC    CMDPROT   HELLO    LOGOFF
               LOGON   NETPUSH   NETRECV   OBSFILL
             or the name of a user-implemented task.


ALARM, %BACKG task -- see MPEX manual for details
AUDITC, %BACKG task -- see MPEX manual for details
CMDPROT, %BACKG task -- see MPEX manual for details
HELLO, %BACKG task -- see MPEX manual for details
LOGOFF, %BACKG task -- see MPEX manual for details
LOGON, %BACKG task -- see MPEX manual for details
NETPUSH, %BACKG task -- see MPEX manual for details
NETRECV, %BACKG task -- see MPEX manual for details
OBSFILL, %BACKG task -- see MPEX manual for details

   %SEC BACKG STARTJOB
   %SEC BACKG START,LOGOFF
   %SEC BACKG STOP,LOGOFF
   %SEC BACKG SHOW
   %SEC BACKG STOPJOB

Controls the BACKG background task job.  Please see the documentation for
%BACKG in the MPEX Commands chapter of the MPEX User Manual for details.

CHANGE


%SEC CHANGE ``contents
%SEC CHANGE
NOVERIFY, %SEC CHANGE keyword
QUIET, %SEC CHANGE keyword
KEY=, %SEC CHANGE keyword
NAME, %SEC CHANGE keyword
TERMINALS, %SEC CHANGE keyword
DAYS, %SEC CHANGE keyword
TIME, %SEC CHANGE keyword
MENU, %SEC CHANGE keyword
INHERIT, %SEC CHANGE keyword
NOPASS, %SEC CHANGE keyword
ASKPASS, %SEC CHANGE keyword
YESPASS, %SEC CHANGE keyword
VEPASS, %SEC CHANGE keyword
ALLPASS, %SEC CHANGE keyword
userfieldname, %SEC CHANGE keyword

   %SEC CHANGE userset [(selectioncondition)] [;NOVERIFY|QUIET]
            [;KEY=[newsession|=,]newuser|=.newaccount|=]
            [;NAME=user's real name]
            [;TERMINALS=[NOT] ldev1,ldev2,...,ldevN]
            [;DAYS=dayfrom-dayto]
            [;TIME=timefrom-timeto]
            [;MENU=menufilename]
            [;INHERIT=[parentsession,]parentuser.parentaccount]
            [;NOPASS|ASKPASS|YESPASS]
            [;VEPASS=passnum,newpass]...
            [;ALLPASS]
            [;userfieldname=val]...

   %SEC CHANGE @.AP-@,MGR.AP;MENU=APMENU.DATA
   %SEC CHANGE JOE,$AT.PROD;VEPASS=3,NEWPASS

Changes the user profiles in the given userset.


TERMINALS= ALL, special %SEC CHANGE keyword value
TIME= ALL, special %SEC CHANGE keyword value
DAYS= ALL, special %SEC CHANGE keyword value
MENU= NONE, special %SEC CHANGE keyword value
MENU= $MENU-FILE, special %SEC CHANGE keyword value

  * ";NAME=", ";TERMINALS=", ";DAYS=", ";TIME=", and ";MENU=" change the
     relevant user profile fields -- format is the same as in "%SEC ADD".  To
     remove existing terminal, day-of-week or time-of-day restrictions, specify
     "ALL" (e.g.  ";TERMINALS=ALL").  To remove a menu file, say ";MENU=NONE"
     (no menu file, even if $MENU-FILE is set) or ";MENU=$MENU-FILE" (no menu
     file in the user profile, though $MENU-FILE, if set, can impose one).


INHERIT= NONE, special %SEC CHANGE keyword value

  * ";INHERIT=" changes the profile to inherit from a different profile.  To
     make an inheriting profile into a non-inheriting profile, just specify
     "NONE" (e.g.  ";INHERIT=NONE").

   * ";KEY=" changes the user profile's session ID, MPE user ID, and account
     name; you may use an "=" in place of any of these three values to mean
     "leave this value the same".  For example, to change all profiles in the
     TEST account to the PROD account, you might say:

        %SEC CHANGE @.TEST; KEY==,=.PROD

   * ";NOPASS" changes the user profile(s) to have no SECURITY passwords.

   * ";ASKPASS" changes the user profile(s) to have their passwords prompted
     for when the users first log on -- to set a temporary password, say
     ";ASKPASS;VEPASS=1,temppass".

   * ";YESPASS" changes the user profile(s) to have SECURITY passwords -- say
     ";YESPASS;ALLPASS" to do the change and be prompted for the new passwords.

   * ";ALLPASS" prompts for all the SECURITY passwords for all the profiles in
     the userset.

   * ";VEPASS=passnum,newpass" sets the given password to the given value, e.g.
     ";VEPASS=3,XYZZY" sets password #3 to the value "XYZZY".  The password
     number is its line number in the VEPROMPT.DATA.VESOFT file (or whatever
     other file is configured using $VEPASS-PROMPT-FILE), counting from 1; if
     you only have one SECURITY password configured, it is #1.

   * User-defined fields, if configured, can be specified much as they can be
     in the %SEC ADD command -- for instance, if you have user-defined fields
     DEPT and EXPDATE, you can change them by saying

        %SEC CHANGE @.AP-@,MGR.AP;DEPT=AP;EXPDATE=1/1/91

CLEARLOG


%SEC CLEARLOG ``logging`contents
%SEC CLEARLOG

   %SEC CLEARLOG

Clears the SECURITY log file.

DEACTIVATE


%SEC DEACTIVATE ``contents
%SEC DEACTIVATE
NOVERIFY, %SEC DEACTIVATE keyword
QUIET, %SEC DEACTIVATE keyword

   %SEC DEACTIVATE userset [(selectioncondition)]
                           [;NOVERIFY|QUIET]

   %SEC DEACTIVATE @.@-@.SYS(LASTLOGONDATE<TODAY-90 &
                             and LASTLOGONLDEV<>0)

Deactivates all the user profiles indicated by the given userset (the same way
that the passwords would have been deactivated by an excessive number of
invalid logon attempts; INVALIDATTEMPTS field is set to 32767).  Users will be
forbidden from logging on under those user profiles until you do a "%SEC
REACTIVATE" to reactivate them.

DELETE


%SEC DELETE ``contents
%SEC DELETE
NOVERIFY, %SEC DELETE keyword
QUIET, %SEC DELETE keyword

   %SEC DELETE userset [(selectioncondition)]
                       [;NOVERIFY|QUIET]

   %SEC DELETE @.@-@.SYS(LASTLOGONDATE<TODAY-90 &
                         and LASTLOGONLDEV<>0)
   %SEC DELETE @.@(NOT USEREXISTS(USER+"."+ACCOUNT))

Deletes the user profiles in the given userset and all their inheriting user
profiles (because if a parent is deleted, the inheriting profile will not be
usable anyway).  Remember that, like most other commands, "%SEC DELETE"
displays all the profiles that will be deleted (unless you specify ";NOVERIFY"
or ";QUIET"), so you shouldn't have any unwelcome surprises.

The user profiles that are to be deleted not because they're in the userset but
because they're inheriting are displayed as "----Will delete A,B.C (=D,E.F)"
where "A,B.C" is the inheriting profile and "D,E.F" is the parent profile.

DUMP


%SEC DUMP ``contents
%SEC DUMP
OUT=, %SEC DUMP keyword
SORT=, %SEC DUMP keyword
OLDDATE, %SEC DUMP keyword
NEWDATE, %SEC DUMP keyword
INTDATE, %SEC DUMP keyword

   %SEC DUMP userset [(selectioncondition)] ;OUT=filename[;NEWDATE]
                   [;SORT=field1[:len1][:'DESC']
                        [,field2[:len2][:'DESC']...]
                   [;OLDDATE|NEWDATE|INTDATE]

   %SEC DUMP @.@;OUT=dumpfile
   %SEC DUMP @.PROD;OUT=PRODUSRS;SORT=SESSION:8

Copies all of the profiles for the given userset from the SECURITY data file to
a flat file.  This gives you a way to write your own reports on SECURITY user
profiles.  (For performance reasons, SECURITY user profiles are not kept in an
IMAGE database or KSAM file; they are kept in a special privileged file using
VESOFT's own internal access mechanism.)

Format of the file created by the %SEC DUMP command

                    |     |Array|Offset|Length |   Notes
Field name          |Type | size|   (bytes)    | (see below)

ACCOUNT             | STR |   8 |    0 |     8 |   (1)
USER                | STR |   8 |    8 |     8 |   (1)
SESSION             | STR |   8 |   16 |     8 |   (1)
TERMALLOW|DISALLOW| STR |   2 |   24 |     2 |   (2)
TERMINALS           | INT |  30 |   26 |    60 |
DAYBEGIN            | INT |   1 |   86 |     2 |
DAYEND              | INT |   1 |   88 |     2 |
HOURBEGIN           | INT |   1 |   90 |     2 |
HOUREND             | INT |   1 |   92 |     2 |

INVALIDATTEMPTS     | INT |   1 |   94 |     2 |   (7)
MENU                | STR |  36 |   96 |    36 |   (1)
LASTLOGONDATE       | STR |   8 |  132 |     8 |   (3)
NAME                | STR |  30 |  140 |    30 |   (4b)
HAS|NO|ASKVEPASS  | STR |   2 |  170 |     2 |   (5)
encryption type     | INT |   1 |  172 |     2 |   (8)
reserved (filler)   |     |     |  174 |    60 |   (6)
LASTPASSCHGDATE     | DATE|   8 |  234 |     8 |   (3)
reserved (filler)   |     |     |  242 |    60 |

LASTLOGONLDEV       | INT |   1 |  302 |     2 |
LASTLOGONTIME       | TIME|   1 |  304 |     4 |
reserved (filler)   |     |     |  308 |     4 |
user defined fields | STR | 256 |  312 |   256 |
PARENTKEY           | STR |  24 |  568 |    24 |   (4a)
reserved (filler)   |     |     |  592 |    24 |
VEPASSWORDS         | INT |  30 |  616 |   120 |
reserved (filler)   |     |     |  736 |    32 |   (9)

UPPERCASE field names match user profile attribute variable names (see "Listing
User Profiles", earlier in this manual).

Notes:

   (1) Left justified, padded with blanks.
   (2) Indicates whether the TERMINALS array contains terminals that the user
       is ALLOWED to use ("Y") or is FORBIDDEN from using ("N").
   (3) By default or if ;OLDDATE is specified, this field is stored as
       "YY/MM/DD", including slashes.  If ;NEWDATE is specified, this field is
       stored as "YYYYMMDD".  If ;INTDATE (which stands for INTernal DATE) is
       specified, this field is stored however it's stored in our internal file
       -- YY/MM/DD for dates written by version 25.  and earlier, YYYYMMDD for
       dates written by version 26.  and later.  The default is ;OLDDATE for
       compatibility with older versions.
  (4a) If this field contains data, it indicates the actual parent profile in
       the same format as the profile key.
  (4b) If the first character is "=", this refers to a parent profile.  It will
       be followed by the 3 fields (session, user, account) that identify the
       parent profile, each left-justified within an 8-character field
       (blank-padded), and separated by a "," and ".".  For example, "=MICHAEL
       ,PARENT  .PROFILE "
       If not this, the NAME field now contains just the user's real name.
       Attribute variables ORIGNAME and ULTIMATENAME are synonyms for this
       field.
   (5) This field can contain one of the values:
       N - this user is not to be asked passwords;
       Y - this user is to be asked passwords, and the answers are current;
       A - this user is to be asked passwords, but has not yet logged on "for
           the first time" since this option was set.  In this case, ANSWERS[0]
           contains the TEMPORARY password (encrypted) for this user.
       O - this user has been obsoleted.
   (6) This is the one-way encrypted SECURITY password.  A value of "-1"
       indicates this password is unused.
   (7) A value of 32767 in this field indicates this profile has been
       deactivated.
   (8) Indicates which version of the encryption method is used to encode user
       passwords.  A "3" here indicates version 2.3 or prior, and "4" indicates
       version 2.4 or later.  If this field contains a "3" prior to conversion
       to the current version, this will remain unchanged until the user
       CHANGES his or her passwords, at which point this will be changed to
       "4".
   (9) Total record length = 768 bytes.

DUMPOBS


%SEC DUMPOBS ``contents
%SEC DUMPOBS
OUT=, %SEC DUMPOBS keyword
ACCOUNT, %SEC DUMPOBS keyword
GROUP, %SEC DUMPOBS keyword
USER, %SEC DUMPOBS keyword
SORT=, %SEC DUMPOBS keyword
OLDDATE, %SEC DUMPOBS keyword
NEWDATE, %SEC DUMPOBS keyword
OLDDATE, %SEC DUMPOBS keyword
INTDATE, %SEC DUMPOBS keyword

   %SEC DUMPOBS mpeuserset ;OUT=filename
                           ;ACCOUNT|GROUP|USER
                           [;OLDDATE|NEWDATE|INTDATE]
                           [;SORT=field1[:len1][:'DESC']
                                [,field2[:len2][:'DESC']...]

   %SEC DUMPOBS @.@;OUT=dumpfile;ACCOUNT
   %SEC DUMPOBS @.PROD;OUT=PRODUSRS;USER;SORT=USER:8

Copies the MPE password obsolescence information for the given userset from the
SECURITY data file to a flat file.  (For performance reasons, MPE password
obsolescence information is not kept in an IMAGE database or KSAM file.
Instead, a special privileged file which uses VESOFT's own internal access
mechanism is used.)

You must specify either ACCOUNT, GROUP or USER.

When specifying ;SORT= information, the [:LEN] parameter is required for
ALPHANUMERIC fields (such as USER or ACCT), but must not be specified for
NUMERIC ONLY or DATE fields (such as OBSDAYS or CHGDATE).

Format of the file created by %SEC DUMPOBS ...  ;ACCOUNT

                   |     |Array|Offset|Length |   Notes
  Field Name       |Type | size|   (bytes)    | (see below)

    filler         |     |     |    0 |   8   |    (1)
    ACCT           | STR |   8 |    8 |   8   |
    filler         |     |     |   16 |   8   |    (1)
    CHGDATE        | DATE|   8 |   24 |   8   |    (2)
    filler         |     |     |   32 |   8   |    (1)
    OBSDAYS        | INT |   1 |   40 |   2   |    (3)
    WARNDAYS       | INT |   1 |   42 |   2   |    (3)

Format of the file created by %SEC DUMPOBS ...  ;USER

                   |     |Array|Offset|Length |   Notes
  Field Name       |Type | size|   (bytes)    | (see below)

    USER           | STR |   8 |    0 |   8   |
    ACCT           | STR |   8 |    8 |   8   |
    filler         |     |     |   16 |   8   |    (1)
    CHGDATE        | DATE|   8 |   24 |   8   |    (2)
    filler         |     |     |   32 |   8   |    (1)
    OBSDAYS        | INT |   1 |   40 |   2   |    (3)
    WARNDAYS       | INT |   1 |   42 |   2   |    (3)
    filler         |     |     |   44 | 150   |    (1)

Format of the file created by %SEC DUMPOBS ...  ;GROUP

                   |     |Array|Offset|Length |   Notes
  Field Name       |Type | size|   (bytes)    | (see below)

    filler         |     |     |    0 |   8   |    (1)
    ACCT           | STR |   8 |    8 |   8   |
    GROUP          | STR |   8 |   16 |   8   |
    CHGDATE        | DATE|   8 |   24 |   8   |    (2)
    filler         |     |     |   32 |   8   |    (1)
    OBSDAYS        | INT |   1 |   40 |   2   |    (3)
    WARNDAYS       | INT |   1 |   42 |   2   |    (3)

Notes:

   (1) Filler (currently not used).
   (2) Last date on which the password was changed.  By default or if ;OLDDATE
       is specified, this field is stored as "YY/MM/DD", including slashes.  If
       ;NEWDATE is specified, this field is stored as "YYYYMMDD".  If ;INTDATE
       (which stands for INTernal DATE) is specified, this field is stored
       however it's stored in our internal file -- YY/MM/DD for dates written
       by version 25.  and earlier, YYYYMMDD for dates written by version 26.
       and later.  The default is ;OLDDATE for compatibility with older
       versions.
   (3) Number of days left in the warning period or until the obsolescence
       period.

(NEW) ENCRYPT/DECRYPT


%SEC ENCRYPT and %SEC DECRYPT SECURITY commands``contents`news
%SEC ENCRYPT and %SEC DECRYPT SECURITY commands

   %SEC ENCRYPT mpexfileset

   %SEC DECRYPT mpexfileset

Examples:  %SEC ENCRYPT datafile
           Please type the encryption key:  (The key is not displayed)
           Please type the key again     :
           -----Encrypting DATAFILE.WORK.VESOFT

           %PRINT datafile
           Please type the decryption key:  (Prompts for key value)
             (The contents of the file are displayed)

           %SEC DECRYPT datafile
           Please type the decryption key:  (Again, not displayed)
           -----Decrypting DATAFILE.WORK.VESOFT

The %SEC ENCRYPT and DECRYPT commands allow you to scramble the contents of a
file in such a way as to make the file unreadable until it is decrypted with
the original key value.  The MPEX %PRINT command has been enhanced to recognize
encrypted files and will prompt for the key value before reading the encrypted
file.  In addition, the MPEX %LISTF...,ID mode will note that the file was
encrypted, including the date, time, and user ID of the person who encrypted
the file.

The %SEC ENCRYPT command will not re-encrypt an encrypted file, and the %PRINT
and %SEC DECRYPT commands will not decrypt a file if a different key value is
entered.

Note that these commands will accept a fileset.  The %SEC DECRYPT command will
only prompt once for an encryption key value to use for all files in the
fileset.  Any files in the fileset with a different key (as well as files that
were not encrypted to begin with) will remain unchanged and a warning message
will be generated.

HELP


%SEC HELP ``contents
%SEC HELP

   %SEC HELP [keyword]

Gets interactive help on the given keyword.

LISTLOG


%SEC LISTLOG ``logging`contents
%SEC LISTLOG
SORT=, %SEC LISTLOG keyword

   %SEC LISTLOG [(selectioncondition)]
                [;SORT=field1[:len1][:'DESC']
                     [,field2[:len2][:'DESC']]...]
                [;LP]

   %SEC LISTLOG ACCOUNT<>'TEST' and (OPADD or OPVIOLATION); &
                SORT=ACCOUNT:8, USER:8; LP


SECLIST, formal file designator for printed output of LISTLOG
those records in the SECURITY log file that match the given selection
condition.  The listing is sent to the terminal unless you specify ";LP", in
which case it is sent to the line printer (the formal file designator is
SECLIST, with default device class of LP).  This selection condition is an
arbitrary logical expression just like the userset selection condition, but
since it selects log records you should use SECURITY log record attribute
variables (see "Selecting Log Records To Be Listed" later in this manual), not
user profile attribute variables.

By default, the log file is sorted in ascending order by DATE and TIME.  You
can change this to sorting by TERMINAL, DATE, and TIME by using the ;SORT=
keyword as follows:

   %SEC LISTLOG OPLOGON and ACCOUNT="PROD"; &
        SORT=TERMINAL,DATE,TIME

To sort in descending order, you can say something like
";SORT=TERMINAL,DATE:'DESC',TIME:'DESC'".

One special concern is sorting on string fields -- for those, you must specify
the length of the field being sorted, e.g.

   ;SORT=ACCOUNT:8,USER:8,SESSION:8,DATE:'DESC',TIME:'DESC'

This indicates that you want to sort (in ascending order) by account, user, and
session (each 8 characters long), and within that in descending order by DATE
and TIME.

For more details on the SECURITY logging facility, please see the chapter
"SECURITY's Logging Facility" in this manual.

LISTMPEOBS


%SEC LISTMPEOBS ``expiration`contents
%SEC LISTMPEOBS
SORT=, %SEC LISTMPEOBS keyword

   %SEC LISTMPEOBS userset [(selectioncondition)]
                           [;USER|GROUP|ACCOUNT]
                           [;SORT=field1[:len1][:'DESC']
                                [,field2[:len2][:'DESC']]...]
                           [;LP]

   %SEC LISTMPEOBS @.@;USER; LP

Lists SECURITY's MPE password obsolescence information, including when the
password was last changed, and how long until it will expire, the current
OBS-DAYS and WARN-DAYS settings, and whether or not the user is allowed to
change his own password.  (This command reports on data collected by the
OBSFILL task, which you must set to run under the BACKG job every night --
please see %BACKG in the MPEX Commands chapter of the MPEX User Manual for
details.)

Only those users/groups/accounts that actually have a password, and for whom
obsolescence is enforced, will be listed


SECLIST, formal file designator for printed output of LISTMPEOBS
default, the output goes to the terminal, but ";LP" sends it to the line
printer (formal file designator SECLIST; defaults to device class LP).

The output is normally sorted by account and user, account and group, or
account (depending on whether you select USER, GROUP or ACCOUNT); however, if
you want to sort it differently, you can use the ";SORT=" keyword.

LISTUSER


%SEC LISTUSER ``contents
%SEC LISTUSER
SORT=, %SEC LISTUSER keyword

   %SEC LISTUSER userset [(selectioncondition)]
                         [;SORT=field1[:len1][:'DESC']
                              [,field2[:len2][:'DESC']]...]
                         [;LP]

   %SEC LISTUSER @.@-@.GAMES(NOVEPASS or ASKVEPASS); LP


SECLIST, formal file designator for printed output of LISTUSER
all the profiles in the given userset -- by default, the output goes to
the terminal, but ";LP" sends it to the line printer (formal file designator
SECLIST; defaults to device class LP).  In addition, since there is more room
on the page, the LP format listing also includes the user's real name (if
defined), the last logon date, and the last password change date for this
profile.  If you have a terminal that can display 132 columns, here is a little
trick that you can do to display all of this information:


Redirecting SECLIST to a 132-column terminal

  <<First, set your terminal to 132 column mode>>
   %:FILE SECLIST=$STDLIST
   %SEC LISTUSER @.@;LP

The output is normally sorted by account, user, and session; if, however, you
want to sort it differently, you can use the ";SORT=" keyword.  The fields
specified with ";SORT=" can be any of the user profile variables described in
the "%SEC Commands: General Syntax" chapter above.  For further discussion of
the ":'DESC'" and ":lenX" parameters, see the "%SEC LISTLOG" command.

One special concern is sorting on string fields -- for those, you must specify
the length of the field being sorted.

(NEW) LOAD


%SEC LOAD, SECURITY command``contents`news
%SEC LOAD, SECURITY command
ADD, %SEC LOAD keyword
ASK, %SEC LOAD keyword
UPDATE, %SEC LOAD keyword

%SEC LOAD dumpfile[;ADD][;UPDATE][;ASK]

EXAMPLE:
  %SEC LOAD SYSADUMP;ADD
  %SEC LOAD dumpfile;UPDATE;ASK
  %SEC LOAD ALPHADMP;ADD;UPDATE

Loads profiles from a file created by the %SEC DUMP command into the SECURITY
data file.  This can be especially useful if you need to merge users from
several different CPUs into one.

You must specify at least one keyword, either ;ADD or ;UPDATE or both.

;ADD means add new profiles, but don't update existing ones.
;UPDATE means update existing profiles, but don't add new ones.
;ADD;UPDATE means add any new profiles AND update any existing ones.
;ASK means for EACH profile in the dumpfile, ask if you want to process that
   particular profile.

OBSMPEPASS


%SEC OBSMPEPASS ``mpe`passwords`expire`contents
%SEC OBSMPEPASS
NOVERIFY, %SEC OBSMPEPASS keyword
QUIET, %SEC OBSMPEPASS keyword

   %SEC OBSMPEPASS mpeuserset [;NOVERIFY|QUIET]

   %SEC OBSMPEPASS @.@-@.TEST(CAP("SM") or CAP("AM") or CAP("PM"))

Obsoletes the MPE passwords of the MPE users in the given MPE userset.  The
effect on the users is exactly as if the users' passwords had not been changed
in the number of days given by the $MPE-U-OBS-DAYS keyword in
SECURCON.DATA.VESOFT.  This can be very useful when you need to force everyone
to change all their passwords (assuming, of course, that you've set
$MPE-OBS-PASSCHG).

OBSVEPASS


%SEC OBSVEPASS ``vepasswords`expire`contents
%SEC OBSVEPASS
NOVERIFY, %SEC OBSVEPASS keyword
QUIET, %SEC OBSVEPASS keyword

   %SEC OBSVEPASS userset [(selectioncondition)]
                          [;NOVERIFY|QUIET]

   %SEC OBSVEPASS @.AP+@,CLERK.PROD

Obsoletes the SECURITY passwords of the user profiles in the given userset.
The effect on the users is exactly as if the profiles' passwords had not been
changed in the number of days given by the $VE-OBS-DAYS keyword in
SECURCON.DATA.VESOFT.  This can be very useful when you need to force everyone
to change all their passwords (assuming, of course, that you've set
$VE-OBS-PASSCHG).

PASSWORD


%SEC PASSWORD ``passwords`contents
%SEC PASSWORD
%SEC PASSWORD, see also SEC VEPASSWORD for SECURITY passwords

   %SEC PASSWORD

Lets a user change his own MPE password, much as he could with the RUN
MAIN.PUB.VESOFT,PASSWORD.  Use the %SEC VEPASSWORD command to change your
SECURITY password.

REACTIVATE


%SEC REACTIVATE ``contents
%SEC REACTIVATE
NOVERIFY, %SEC REACTIVATE keyword
QUIET, %SEC REACTIVATE keyword

   %SEC REACTIVATE userset [(selectioncondition)]
                           [;NOVERIFY|QUIET]

   %SEC REACTIVATE JOE,$AT.PROD+@.TEST

Reactivates a set of user profiles that may have been previously deactivated
using the %SEC DEACTIVATE command or due to an excessive number of invalid
logon attempts.

(NEW) SECDUMP


%SEC SECDUMP, SECURITY command``contents`news
%SEC SECDUMP, SECURITY command
OUT=, %SEC SECDUMP keyword

   %SEC SECDUMP;OUT=filename

   %SEC SECDUMP;OUT=dumpfile

Although this command is similar to the %SEC DUMP command, the file produced is
not in the same format and cannot be used with the %SEC SECLOAD command.  (The
%SEC DUMP command creates a file of profiles in a format similar to our
original IMAGE database which is then used by reporting tools).  Instead, the
%SEC SECLOAD command must be used to process the file created by this command.

This command is used when expanding the SECURG datafile in order to increase
the total number of profiles allowed.  (see the Changing The Capacity Of The
SECURG file section of the special topics for details.)

(NEW) SECLOAD


%SEC SECLOAD, SECURITY command``load`contents`news
%SEC SECLOAD, SECURITY command
IN=, %SEC SECLOAD keyword
MAXPROFILES=, %SEC SECLOAD keyword
FLIMIT=, %SEC SECLOAD keyword
CLEANUF, %SEC SECLOAD keyword

   %SEC SECLOAD;IN=filename
                [;MAXPROFILES=expected profile limit]
                [;FLIMIT=SECURG file limit]
                [;CLEANUF]

   %SEC SECLOAD;IN=dumpfile;MAXPROFILES=15000;FLIMIT=20000

Although this command is similar to the %SEC LOAD command, the file to be
loaded is in a different format than that created by %SEC DUMP.  The file to be
loaded must be built using the %SEC SECDUMP command.

This command is primarily used to increase the total number of profiles allowed
on a system.  The ;MAXPROFILES= and ;FLIMIT= keywords specify the internal
limit to the number of profiles and the initial FLIMIT of the file
respectively.  Note that these keywords only take effect if the SECURG file
doesn't exist at the time the command is entered.  (see the Changing The
Capacity Of The SECURG file section of the special topics for details.)

The ;CLEANUF parameter instructs the loading process to inspect the
user-defined field area of the incoming profiles and strip out any user-defined
fields that do not have a corresponding entry in your SECURCON data file (this
usually only occurs when merging two separate systems onto a single machine).

SECURCAP


%SEC SECURCAP ``capacity`contents
%SEC SECURCAP

Syntax:    %SEC SECURCAP newcapacity

Example:   %SEC SECURCAP 20000

SECURITY keeps the user profiles and MPE password obsolescence data in a
special file called SECURG.DATA.VESOFT.  When the file is first built, there is
a limit of 9999 records.  This should cover most systems, but if you have an
unusually large number of users, you may find that you need to increase the
capacity of this file.  Use the %SEC SHOWCAPACITY command (documented below) to
see the current limit to the file and a rough estimate of how many more entries
may be made to the file.

SHOW


%SEC SHOW ``contents
%SEC SHOW
LDEV=, %SEC SHOW keyword
ALL, %SEC SHOW keyword
SECURCON=, %SEC SHOW keyword

   %SEC SHOW [session,]user.account[,group]
             [;LDEV=device] [;ALL] [;SECURCON=filename]

   %SEC SHOW JOE,MGR.PROD,TEST;LDEV=20;SECURCON=TESTSECC

Shows what SECURITY parameters will be enabled for a user logging on with the
given logon and onto the given LDEV (default is the current LDEV).  Normally
only the non-default settings will be shown, but ;ALL will cause all the
settings to be shown.

If you're planning to roll in a new SECURCON.DATA.VESOFT file and want to
verify that you have entered the correct $ keywords (and that the syntax is
correct), you can use the ;SECURCON= keyword of the %SEC SHOW command.  This
will show you what settings would apply to this user according to the file
defined in the ;SECURCON= keyword without actually logging on as that user or
altering the live SECURCON file.

(NEW) SHOWCAPACITY


%SEC SHOWCAPACITY, SECURITY command``capacity`contents`news
%SEC SHOWCAPACITY, SECURITY command

%SEC SHOWCAPACITY
SECURG end of file is 5818, file limit is 20000, room for 14182 records.

This means room for a total of
    14182 user profile entries or
  1446564 terminal entries or
   255276 stream authorization entries or
    70910 MPE user password obsolescence entries or
   283640 MPE account password obsolescence entries or
   283640 MPE group password obsolescence entries or
   255276 inheritance cross-reference entries,
or for some combination of the above.


SETCAPACITY, %SEC command to increase the capacity of SECURG
make room for more entries, execute the SECURITY command
   SETCAPACITY numentries

However, there is a maximum of at most about 15030 user profile entries,
of which 2380 are currently in use.

SECURITY keeps the user profiles, MPE password obsolescence data, and other
related data in a special file called SECURG.DATA.VESOFT.  This command shows
the current file limit for this file and gives a rough estimate of how many
more entries may be made to this file.  If you are running out of room, you
will need to issue a %SEC SECURCAP command to increase the file limit.

Of particular importance is the last line of the display which shows the actual
maximum number of profiles that may be in this file.  If the number of profiles
in use is near the profile limit, then you will need to expand the file using a
method other than %SEC SECURCAP.  The special topics chapter, "Changing The
Capacity Of The SECURG File", describes the process in detail.

(NEW) SHOWSCHED


%SEC SHOWSCHED, SECURITY command``schedule`contents`news
%SEC SHOWSCHED, SECURITY command

Syntax:   %SEC SHOWSCHED [userset]

Examples: %SEC SHOWSCHED
                                                     Last   -Days-
 #A Job Name                 Submitted By            Job #  SMTWRFA -Time-
--- ------------------------ ----------------------- ------ ------- ------
  1 GETDFREE,MANAGER.TECH    RON,MANAGER.SYS       J2016  SMTWRFA 12:10A
  2 DAILY,MGR.XPRESS         RON,MANAGER.SYS       J2017  -MTWRF- 12:15A
  3 DISCLEAN,MANAGER.SYS     RON,MANAGER.SYS              S-----A 12:35A
  4 BACKUP,MANAGER.SYS       RON,MANAGER.SYS       J2020  -MTWRF-  1:30A
  5 REMOTE,USER.XPRESS       RON,MANAGER.XPRESS    J16
      WHENEVER BETWEEN(HPDAY,2,6) and BETWEEN(HPHOUR,8,18) and HPMINUTE=10
  6 REPORT,MANAGER.SYS       RON,MANAGER.SYS       J1032
      WHENEVER (HPDATE=1)
      CHECKEVERY DAY
  7 TESTSCHD,MANAGER.SYS     TOM,MANAGER.VESOFT                 FRI 10:00A

Shows information on jobs scheduled using the ability of STREAMX to schedule
repeating jobs.

The output consists of:
  -  the schedule number (for use with %ABORTJOB and %SEC ABORTJOB),
  -  the logon string that the job will use,
  -  the user ID of the person who submitted the job to the scheduler,
  -  the job number that was used the last time the job ran (or blank if it has
     never run since it was scheduled),
  -  information regarding what days, times, and/or conditions that the job
     should run under.

See the BATCH ACCESS...  section of this manual for details.

SYNTAX


%SEC SYNTAX ``contents
%SEC SYNTAX

   %SEC SYNTAX [command]

   %SEC SYNTAX CHANGE
   %SEC SYNTAX OBSMPEPASS

This command is a "shortcut" for getting the exact syntax of a particular %SEC
command.  It is useful if you already know the command you need, but can't
remember the syntax particulars.  It accesses the on-line HELP facility, but
bypasses the normal menu (see the documentation on the %SEC HELP command for
details).

VEPASSWORD


%SEC VEPASSWORD ``password`contents
%SEC VEPASSWORD
%SEC VEPASSWORD: see also SEC PASSWORD for MPE passwords

   %SEC VEPASSWORD

Lets a user change his own VEPASSWORD, much as he could with the
MAIN.PUB.VESOFT,VEPASSWORD entry point.  Use the %SEC PASSWORD command to
change MPE passwords.

CHANGING WHO MAY OR MAY NOT MODIFY SECURITY USER PROFILES


Changing who may or may not modify SECURITY user profiles ``contents
Changing who may or may not modify SECURITY user profiles


SECURITY user profile maintenance, controlling it
$MAINT-PERMIT, SECURCON file keyword
$MAINT-FORBID, SECURCON file keyword
, only the system manager (and the account manager working in his own
account) may add, change or delete SECURITY user profiles.  However, the system
manager can change this -- either forbid account managers from modifying users,
even in their own account or permit people to modify users whom they normally
couldn't modify.

The $MAINT-FORBID keyword lets you forbid people from adding, changing or
deleting users that they would otherwise be allowed to add, change or delete.
For instance, if you say

   $MAINT-FORBID ADD @.AP MANAGER.AP

you prohibit MANAGER.AP from adding any user to the AP account; if you say

   $MAINT-FORBID CHANGE,DELETE JACK,@.AP+JOE,@.AP MANAGER.AP

you prohibit MANAGER.AP from changing or deleting any user in the AP account
whose session names are JACK or JOE.  Or, if you say

   $MAINT-FORBID  ADD,CHANGE,DELETE  CAP=AM MANAGER.AP MGR.GL

you prohibit MANAGER.AP and MGR.GL from adding, changing or deleting any users
with AM capability.

As you can see, the syntax of the $MAINT-FORBID keyword is

   $MAINT-FORBID operation[,operation,...] targetuserset usersets

This means "FORBID usersets FROM PERFORMING operation(s) ON THE USERS IN
targetuserset".  This can be very useful if you don't entirely trust your
account managers.

(Note that you must not have any spaces inside your 'targetuserset' parameter!
If you want to $MAINT-FORBID or $MAINT-PERMIT operations on several usersets,
you can either specify several usersets connected by '+'s -- e.g.
$MAINT-FORBID ADD @.AP+@.GL+@.PROD ...  -- or specify several $MAINT-FORBID or
$MAINT-PERMIT keywords.)

On the other hand, if you want to let non-account manager users do user
maintenance or let account managers do maintenance of users in other accounts
without having SM capability, you can use the $MAINT-PERMIT keyword:

   $MAINT-PERMIT  @  @.GL+@.PR+@.AR  JACK.ADMIN

      to allow JACK.ADMIN to do anything ("@" = ADD, CHANGE, DELETE, etc.) to
      users in the GL, PR, and AR accounts.

   $MAINT-PERMIT  ADD,CHANGE  @.!HPACCOUNT  JACK.@

      to allow the user "JACK" in any account to add and change users in his
      logon account (@.!HPACCOUNT).  Presumably, "JACK" doesn't have AM
      capability in all accounts.

   $MAINT-PERMIT  @  CAP<>AM&CAP<>SM&CAP<>PM&@.!HPACCOUNT  CAP=AL

      to allow any user with AL (Account Librarian) capability to manipulate
      all users who DON'T have AM, SM or PM (CAP<>AM&CAP<>SM&CAP<>PM) and are
      in his logon account (@.!HPACCOUNT).

As you see, you can be quite precise about who you want to allow to do what to
whom.  In particular, you can indicate both the adding user and the
user-to-be-added by session name, user name, account name or capability; you
can also indicate "a user in the same account as the would-be maintainer" by
specifying "!HPACCOUNT" in place of the account name.  Just as "!HPACCOUNT"
stands for the logon account, so "!HPUSER" stands for the logon (maintainer's)
user and "!HPJOBNAME" stands for the logon job/session name.

However, be very careful! If, for instance, you say

   $MAINT-PERMIT  ADD,CHANGE  @.AP JACK.AP

then it doesn't matter that JACK.AP doesn't have AM capability; he'll easily be
able to get it by changing the account manager's passwords (or adding a new
user profile that can log on to the AM user ID) and then using the user profile
to log on as AM.  You could avoid this by saying

   $MAINT-PERMIT  ADD,CHANGE  @.AP&CAP<>AM JACK.AP

to prohibit JACK.AP from modifying the AM user, but even that isn't perfect if
there are, say, PM users in the account that JACK.AP will be able to get into.

Thus, we recommend that you be very careful when using $MAINT-PERMIT.  Always
think about what capabilities the permitted user will be able to get using the
power you're granting him!

Keep this in mind.  We believe that our default system -- AM can do anything in
his own account, SM can do anything in the system -- is the best, most reliable
solution; the more you work around it with $MAINT-PERMIT, the greater your
chances of opening up a security loophole.

Note that $MAINT-PERMIT and $MAINT-FORBID can permit and forbid more than just
ADD, CHANGE, DELETE.  You can also use them to:

   * Control access to the REACTIVATE entry point (see the chapter on
     Deactivating profiles after unsuccessful logon attempts).

   * Control access to the SHOW entry point (see "Showing User Parameters And
     Applicable Options") -- this is mostly a trouble-shooting option, and a
     normal user should never have to use it; however, we're including it in
     $MAINT-PERMIT and $MAINT-FORBID just in case.

   * Control access to the LISTLOG and LISTUSER entry points.  Note, however,
     that the "targetuserset" for $MAINT-PERMIT and $MAINT-FORBID of LISTLOG
     and LISTUSER is restricted to specifying either users in your own account
     or all users on the system.  Therefore, the only two targetusersets that
     are valid for LISTLOG and LISTUSER are

       - @.!HPACCOUNT, meaning all log records or users in the logon account,
         e.g.

         $MAINT-PERMIT LISTLOG,LISTUSER @.!HPACCOUNT JACK.@

       - @.@, meaning all log records or users in general, e.g.

         $MAINT-PERMIT LISTLOG,LISTUSER @.@ MGR.AUDIT

   * Control access to the CLEARLOG entry point (which clears the SECURITY log
     file).  If you do this, you must specify a "targetuserset" of @.@, e.g.

         $MAINT-PERMIT CLEARLOG @.@ MGR.AUDIT

     If you specify any other targetuserset, the CLEARLOG will not be allowed.

ADDING PROFILES FOR NON-EXISTENT MPE USER IDs


Adding profiles for non-existent MPE user IDs ``contents
Adding profiles for non-existent MPE user IDs
$CHECK-MPE-USER, SECURCON file keyword

Sometimes you may want to add SECURITY profiles for MPE user ids that don't
exist on your system.  For example, you may want to set up SECURITY for
accounts that are only on your system at certain times.  Or, some users like to
set up "parent profiles" (see above) with an MPE user.account of
"PARENT.PROFILE", even though no such user.account actually exists on their
system.  This way, they can delete inheriting users without the fear that they
will accidentally delete the parent profile by mistake.

Adding the keyword

   $CHECK-MPE-USER OFF

indicates that SECURITY should not check to make sure that a user profile added
using MAIN.PUB.VESOFT,ADD corresponds to an existing MPE user (by default,
SECURITY does check this, to detect accidental mistakes).

SECURITY PASSWORD EXPIRATION


SECURITY password maintenance ``contents
SECURITY password maintenance
SECURITY password expiration
Changing passwords automatically

As we discussed above, one of the greatest threats to system security is
chronically unchanged passwords.  The longer a password remains unchanged, the
more likelihood there is that the password will become more and more widely
known, and thus useless as a security device.  The only way to prevent this is
to require periodic changes of passwords, preferably by users themselves
(without intervention by an account manager).

Requiring periodic SECURITY password changes is quite easy.  At its simplest,
you can just add a line to the SECURCON.DATA.VESOFT configuration file:


VE-OBS-DAYS, SECURCON file keyword ``expire
$VE-OBS-DAYS, SECURCON file keyword

    $VE-OBS-DAYS 30

This tells SECURITY that whenever the user logs on and his SECURITY passwords
had been set for more than 30 days, he will be prompted to enter new values for
those passwords.  These new values will then be valid for the next 30 days, at
which point he'll be required to change them again, and so on.

You have a great deal of flexibility in setting up the password expiration
period.  You might, for instance, decide that certain critical accounts should
have their user passwords expire after 20 days, whereas others should expire
after 30 or 45 days, and others might never have to be changed at all.  For
instance, you might put into your SECURCON.DATA.VESOFT file the lines:

   $VE-OBS-DAYS  20  OPERATOR.SYS+@.AP+CAP=SM+CAP=PM
   $VE-OBS-DAYS  30  @.PAYROLL+@.GL+JACK,@.@
   $VE-OBS-DAYS  45  @.TEST+@.PROD

This means that:

   * the SECURITY passwords for OPERATOR.SYS, for all users in the AP account,
     for all users who have SM capability, and for all users who have PM
     capability, have to be changed after 20 days of use;

   * the passwords for all PAYROLL account and GL account users and all users
     configured with session name JACK should be changed after 30 days of use;

   * the passwords for all TEST and PROD account users should be changed after
     45 days of use;

   * and all other SECURITY passwords do not have to be changed at all
     (although they still can be, using :RUN MAIN.PUB.VESOFT,CHANGE).

You also have other options that control SECURITY password obsolescence.  You
may specify


VE-WARN-DAYS, SECURCON file keyword ``expire`warning
$VE-WARN-DAYS, SECURCON file keyword

   $VE-WARN-DAYS 7

so that, starting with 7 days before a user's SECURITY passwords will become
obsolete, he will be warned of the impending expiration at logon time.  You can
also say


VE-WARN-PASSCHG, SECURCON file keyword ``warning`change
$VE-WARN-PASSCHG, SECURCON file keyword

   $VE-WARN-PASSCHG @.@

which indicates that during this "warning period" the user will be prompted for
his new SECURITY passwords at logon time, but will have the chance to hit
control-Y and log on without entering the new passwords (once the passwords are
expired, however, he will have to enter the new passwords to log on).
Similarly, you can say


VE-OBS-PASSCHG, SECURCON file keyword ``expire`change
$VE-OBS-PASSCHG, SECURCON file keyword

   $VE-OBS-PASSCHG OFF

which specifies that once a user's passwords are obsolete, he will not get a
chance to change them, but will instead have to go to his account or system
manager in order to change his passwords.  A useful approach is to combine the
above options and say:

   $VE-OBS-DAYS  30
   $VE-WARN-DAYS  7
   $VE-WARN-PASSCHG  ON
   $VE-OBS-PASSCHG  OFF

which means that passwords expire after 30 days and each user will have 7 days
before his passwords expire to specify new ones; once his passwords expire,
however, he'll have to ask his account or system manager to allow him to log on
again.

Naturally, you can "mix and match" any of the above keywords, and specify
various usersets (e.g.  $VE-WARN-DAYS 7 @.DEV @.PROD) on each keyword
indicating which settings apply to which users.  For starters, though, the
simplest thing you can do is say:

   $VE-OBS-DAYS 30

(or $VE-OBS-DAYS 45 or $VE-OBS-DAYS 60 or something like that) to simply force
all SECURITY passwords to expire after 30 days.

SECURITY PASSWORD HISTORY


SECURITY password history ``contents
SECURITY password history


VE-PASSHIST-DAYS, SECURCON file keyword
$VE-PASSHIST-DAYS, SECURCON file keyword
, when a user's password expires and he changes it, he must change it
to some different value; it's not enough for him to re-enter his old password
-- he must specify a new, different one.

However, what prevents him from changing back to the old password next month
(or whenever his new password expires), thus going back and forth between two
passwords? Reusing an old password is certainly not as bad as having the same
password all the time, but it is also not as good as making sure that every
month each user picks a genuinely new password.

With the Password History feature, you can make sure that a user can not reuse
an old password for a given amount of time (e.g.  6 months or a year).  For
instance, you can say:

   $VE-PASSHIST-DAYS 180

(which indicates that nobody can reuse any password within a 180-day period) or

   $VE-PASSHIST-DAYS 180 @.GL
   $VE-PASSHIST-DAYS 365 OPERATOR.SYS JANE.DEV

(which indicates that the GL account users can't reuse theirs for 180 days,
OPERATOR.SYS and JANE.DEV can't reuse theirs for 365 days, and everybody else
does not have any restriction on password reuse).  SECURITY will remember the
passwords each user has used in the past, say, 180 or 365 days, and will make
sure that his new password is different.

For example, say a user logs on, SECURITY detects that his SECURITY password
will soon be obsoleted, and prompts him for a new one:

   :HELLO LOUIS,CLERK.AP
   ...
   **********************************************************

   Your SECURITY password will expire in 7 days!

   **********************************************************

   Please enter your new SECURITY passwords now:
   ENTER YOUR SECURITY PASSWORD:    << user types password >>
   Error: You may not reuse passwords for 180 days.

   ENTER YOUR SECURITY PASSWORD:    << user types new password >>
     << User has entered an entirely new password, everything's OK >>
   Welcome!  You are now signed on.

Similarly, if a user changes his password explicitly by running
MAIN.PUB.VESOFT,VEPASSWORD, the non-reuse requirement will also be enforced --
all recently used passwords will be rejected.

Note that this feature is only available for users that use exactly one
SECURITY password.  If a user has several SECURITY passwords, the
$VE-PASSHIST-DAYS keyword will not function.  However, most sites that have
multiple SECURITY passwords use them as "personal profile" passwords ("What's
your mother's maiden name?", etc.), which it doesn't make sense to obsolete
anyway.

ENFORCING SECURITY PASSWORD STANDARDS (E.G.  MINIMUM LENGTH)


Enforcing SECURITY password standards ``contents
Enforcing SECURITY password standards
Minimum password length: SECURITY passwords

Users' laziness often defeats system security.  If given the chance, users will
often specify passwords that are easy to guess -- obvious things like their
names or one- or two- character passwords that can be easily observed when the
user is typing them in.

One thing that SECURITY allows you to do to avoid this is to specify an editing
mask for each SECURITY password.  This mask should be specified in the
VEPROMPT.DATA.VESOFT file on the same line as the SECURITY password prompt:


PASS-EDIT, VEPROMPT.DATA.VESOFT option ``edit`passwords
$PASS-EDIT, VEPROMPT.DATA.VESOFT option

   $PASS-EDIT "????@" PLEASE ENTER YOUR SECURITY PASSWORD:

This particular edit mask -- ????@ -- specifies that each password must be four
characters followed by zero or more other characters; in other words, each
password must be at least four characters long.  (Note that this edit mask is
very much like MPE's wildcard patterns used in mpefilesets, usersets, etc.)

The reason you may need to put the edit mask in the VEPROMPT.DATA.VESOFT file
rather than in the SECURCON.DATA.VESOFT file (which is where other options such
as the MPE password edit mask go) is that if you have several SECURITY
passwords configured, you might want to have different edit masks for each one.

Of course, $PASS-EDIT also works perfectly well if you only use one password
per profile; you can even put it into a $VEPASS-PROMPT or a $VEPASS-TEMP-PROMPT
keyword in the SECURCON file, e.g.


PASS-EDIT, $VEPASS-PROMPT option ``edit`passwords
$PASS-EDIT, $VEPASS-PROMPT option
$PASS-EDIT, $VEPASS-TEMP-PROMPT option

   $VEPASS-TEMP-PROMPT "$PASS-EDIT '????@' ENTER TEMPORARY PASSWORD:"
   $VEPASS-PROMPT "$PASS-EDIT '????@' SECURITY PASSWORD:"

One other very useful application for password editing is to discourage obvious
passwords, like the user's last name or nickname or something like that.  One
thing that some of our users like to do (in fact, this is required by some
standards) is to require that each password contain a digit, which makes it
much less likely that the user will make it something really obvious.  For
instance, you might say:

   $PASS-EDIT "????@#" PLEASE ENTER YOUR SECURITY PASSWORD:

This makes sure that the user's password is five or more characters long and
its last character is a digit.

FLEXIBLE SECURITY PASSWORD EDIT CHECKING


Flexible SECURITY password edit checking ``contents
Flexible SECURITY password edit checking
$VEPASS-FORBID, SECURCON file keyword

You can impose virtually any arbitrary edit checks for SECURITY user profile
passwords using the $VEPASS-FORBID keyword.  Say, for instance, that you want
to prohibit any SECURITY password from:

   * being entirely alphabetic;

   * being entirely numeric;

   * containing any 'Q' or 'Z';

   * containing three or more consecutive identical characters;

   * being the same as the user profile's session ID, user ID or account ID;

   * being the same as the MPE user password or account password;

   * being one of the "easily guessable" passwords listed in the
     BADPASS.AUDITDAT.VESOFT file (which is also used by VEAUDIT).

No problem! Just include in your SECURCON.DATA.VESOFT file the following
commands:


ALPHA, string test function

$VEPASS-FORBID "ALPHA(P)" "Password must not be entirely alphabetic"


NUMERIC, string function

$VEPASS-FORBID "NUMERIC(P)" "Password must not be entirely numeric"


POS, string function (finds one string in another)

$VEPASS-FORBID "POS('Q',P)<>0 or POS('Z',P)<>0"
   "Password may not contain Qs or Zs"


MAXCONSECUTIVE, string function

$VEPASS-FORBID "MAXCONSECUTIVE(P)>=3"
   "Password may not contain 3 or more consecutive identical chars"

$VEPASS-FORBID "P=SESSION or P=USER or P=ACCOUNT"
   "Password may not be the same as the session, user or account"

$VEPASS-FORBID "P=VEUSERINFO(HPUSER+'.'+HPACCOUNT).PASSWORD"
   "Password may not be the same as the MPE user password"

$VEPASS-FORBID "ACCOUNT<>'@' and P=VEACCTINFO(ACCOUNT).PASSWORD"
   "Password may not be the same as the MPE account password"


BADPASSWORD, function to look up the BADPASS file

$VEPASS-FORBID "BADPASSWORD(P)" "Password is too easy to guess"


P, SECURCON expression variable for SECURITY password edit checking
the syntax of each $VEPASS-FORBID line:

   $VEPASS-FORBID "expression" "error message" [usersets]

This means "forbid people from setting up passwords that match the given
expression; if such a password is tried, print the given error message".  By
default, this prohibition applies to all SECURITY users; however, you can
restrict this to particular usersets, e.g.

   $VEPASS-FORBID "ALPHA(P)"
      "Password must not be entirely alphabetic"  @.AP

would apply the prohibition only to users in the AP account.

Note that the "expression" parameter can be an arbitrary expression, as
discussed in Appendix -- this is what gives the $VEPASS-FORBID mechanism such
power.  In addition, you also have access to all of the "User Profile Attribute
Variables And Functions" listed in the the "Listing User Profiles" chapter,
above.  You can perform virtually any test on the password value that the user
entered by referring to the special variable named P in a string expression.

The $VEPASS-FORBID tests are applied any time a SECURITY password is changed by
anybody, whether through the CHANGE entry point, through the VEPASSWORD entry
point, as a result of SECURITY password obsolescence or any other way.

The $MPE-PASS-FORBID keyword,

   $MPE-PASS-FORBID "expression" "error message" [usersets]

(syntactically identical to the $VEPASS-FORBID keyword) lets you impose
arbitrary edit checks on MPE passwords.  The main difference is that you can't
use SECURITY profile attributes in the expression; instead, you can use MPE
attribute variables.  See "Flexible MPE User Password Edit Checking", below,
for more details.

PREVENTING A USER FROM ENTERING IDENTICAL PASSWORDS


Preventing a user from entering identical passwords ``contents
Preventing a user from entering identical passwords


VE-DIFF-PASS, SECURCON file keyword ``different`passwords
$VE-DIFF-PASS, SECURCON file keyword
, if you configure SECURITY to have multiple passwords for each user, lazy
users will make all their passwords identical.  This, of course, defeats the
main purpose of multiple passwords (which is to make sure that even if one of
the passwords "leaks out", a would-be violator can't be certain that that's the
one he'll get asked the next time he logs on).  Fortunately, SECURITY can
prevent this.

All you need to do is add a line to your SECURCON.DATA.VESOFT file that says:

   $VE-DIFF-PASS @.@

or, if you want to enable this for only some users,

   $VE-DIFF-PASS @.AP @.GL @.SYS

This way, whenever a user enters his passwords -- at initial user configuration
time, at password expiration time, by running MAIN.PUB.VESOFT,CHANGE, etc.  --
SECURITY will make sure that all his passwords are different.

If all of them are the same or if half the passwords are A and half are B -- in
fact, if any two are identical -- SECURITY will forbid the user from entering
that set of passwords.  With $VE-DIFF-PASS @.@, all of a user's password must
be distinct from one another.

For instance, here's an example conversation:

   ENTER SECURITY PASSWORD A:    << user types FOO >>
   Please enter it again:
   ENTER SECURITY PASSWORD B:    << user types FOO again >>
   Please enter it again:
   Error: System management requires all passwords to be different.

LETTING USERS CHANGE THEIR OWN SECURITY PASSWORDS


Letting users change their own SECURITY passwords ``contents
Letting users change their own SECURITY passwords


Changing SECURITY passwords
VEPASSWORD, MAIN.PUB.VESOFT entry point
$VEPASSCHG-VERIFY, SECURCON file keyword
SECURITY user can easily change his own SECURITY password (or passwords) by
simply saying

   :RUN MAIN.PUB.VESOFT,VEPASSWORD

SECURITY will ask him for his new password(s), of course enforcing whatever
restrictions you have, like $PASS-EDIT or $VEPASS-FORBID (to impose edit masks
on passwords), $VE-DIFF-PASS (to require all of a user's SECURITY passwords to
be different), $VE-PASSHIST-DAYS (SECURITY password history), etc.

If you have multiple SECURITY passwords, the user can simply hit [RETURN] for
any passwords that he does not want to change.  Of course, when not all of the
passwords are changed, this does not stop the password obsolescence clock from
ticking; only a change of all the passwords resets the last change date.

If you want, you can force users to enter their old (current) passwords before
being allowed to change their passwords.  To do this, simply add

   $VEPASSCHG-VERIFY [usersets]

to your SECURCON.DATA.VESOFT file.

Of course, you can still use SECURITY password obsolescence and tell SECURITY
(using the $VE-OBS-PASSCHG or $VE-WARN-PASSCHG keywords) to automatically ask
users for new passwords when the old ones obsolete.  The VEPASSWORD entry point
can, however, allow users to modify their own passwords whenever they feel it's
appropriate (for instance, if they think their old passwords might have been
compromised).  It never hurts to change your passwords more often.


How SECURITY passwords work in batch ``contents
How SECURITY passwords work in batch
$BATCH-VEPROFILE, SECURCON file keyword
Prompts by STREAMX for SECURITY passwords

When you log on online (in a session, from a terminal) as a user that's
protected with $VEPROFILE, you'll be prompted for your SECURITY password.  (If
you have multiple SECURITY passwords, you'll be prompted for a randomly
selected one of them.)

How can all this work in batch? In a batch job, there's nobody who can enter a
SECURITY password (certainly not a random one!) We could have had SECURITY in
batch prompt for some fixed SECURITY password and then make the job stream
author embed the password in the job stream; however, as we often mention,
embedded passwords are a bad thing and should be avoided.

The way we implement security in batch is this:

   * By default, anybody can log on to a $VEPROFILE-protected user in batch!
     This is done for compatibility with older versions of SECURITY and to make
     SECURITY installation as easy as possible.  However, it's your
     responsibility to protect against unauthorized batch access, either by
     retaining MPE passwords or by using the $BATCH-VEPROFILE feature described
     shortly.

   * You may specify in your SECURCON.DATA.VESOFT file a line such as:

        $BATCH-VEPROFILE @.@

     Then, any job streams that

        - are submitted using a normal :STREAM command and

        - log on to users who are protected using $VEPROFILE (and have SECURITY
          passwords enabled)

     will be rejected.  The only way in which jobs that log on as
     $VEPROFILE-protected users (with SECURITY passwords enabled) will be
     allowed is if they're submitted using STREAMX.

     STREAMX will then do all the appropriate checking, including prompting for
     SECURITY passwords, and will then submit the job.  The job will "know"
     that it's submitted with STREAMX and SECURITY will allow it to log on.

Let's look at an example of this.  Say that our SECURCON.DATA.VESOFT file
includes the lines:

   $VEPROFILE @.AP @.GL
   $BATCH-VEPROFILE @.@

This means that users in the AP and GL accounts are protected using SECURITY
user profiles (and have SECURITY passwords); this also means that all users
protected with $VEPROFILE are also protected against unauthorized batch logons.

Now, say that you log on as TOM,CLERK.AP and you try to stream the job:

   !JOB JACK,CLERK.AP
   !RUN AP000.PUB.AP
   ...
   !EOJ

If you submit this job using the normal MPE :STREAM command, it will be
rejected.  After all, you were never prompted for JACK,CLERK.AP's SECURITY
passwords -- how does SECURITY know you're authorized to stream this job
stream?

Say, however, that you stream this job using STREAMX (perhaps you have a
system-wide UDC that redirects the :STREAM command to use STREAMX; or, you may
run STREAMX directly).  What you'd see is something like this:

   STREAMX/3000 Version 27Nymmdd  (VESOFT Inc.  (C) 1980)

   JOB CARD = !JOB JACK,CLERK.AP
   Please enter SECURITY password for JACK,CLERK.AP
   YOUR SECURITY PASSWORD?  << JACK enters his password >>
     #J1234

STREAMX is smart enough to recognize that this job is logging on to a user
who's protected with $VEPROFILE and $BATCH-VEPROFILE; therefore, STREAMX
prompted the person streaming the job for the appropriate SECURITY password.
Since the user TOM should not know the password for the user JACK, Jack must
walk over to Tom's terminal to enter his password.  Now, #J1234 will be able to
log on and proceed normally, since SECURITY knows that its submission was
authorized.

Note that when STREAMX is asking for a SECURITY password, it is (of course)
asking for the password of the user that the job logs on as (in this case,
JACK,CLERK.AP), not that of the user who submits the job!

The same kind of provisions that STREAMX has for avoiding MPE password prompts
also work for avoiding SECURITY password prompts:

   * If a system manager submits a job stream, he will not be required to enter
     a SECURITY password, even if the job stream logs on as a user that is
     protected with $VEPROFILE and $BATCH-VEPROFILE.  The job will be submitted
     and allowed to execute just because the submitter is the system manager.

   * Similarly, if the job's submission is explicitly authorized using a
     $NOPASS entry in the STREAMX.DATA.VESOFT data file (see the Batch Access
     Security...  chapter of this manual for more information on this), the
     streaming user won't be prompted for passwords (either MPE or SECURITY).

   * If an account manager submits a job stream that logs on into his own
     account, he will not be required to enter a SECURITY password.

   * If an ordinary user submits a job stream that logs on under his session
     name, user ID, and account name, he will not be required to enter a
     SECURITY password.

Additionally, if you protect a user with $VEPROFILE and $BATCH-VEPROFILE, other
aspects of SECURITY's user profile security will be implemented, too.  Most
importantly, these include:

   * The requirement that the user profile exist in the database -- if a job
     stream tries to log on as COMPILE,TEST.AP (and this user ID is protected
     with $BATCH-VEPROFILE), then a user profile for COMPILE,TEST.AP will have
     to be set up.

   * Day-of-week/time-of-day restrictions -- if JACK,CLERK.AP is only allowed
     to log on Monday through Friday from 8 AM to 6 PM, his batch jobs will
     face the same requirements.

These requirements are waived for

   * Jobs streamed by the system manager,

   * Jobs explicitly authorized with $NOPASS,

   * Jobs streamed by the account manager in his own account, but

   * not for jobs streamed by a user that log on as himself (since in this case
     the day-of-week/time-of-day restrictions are quite relevant).

This is done to prevent your having to add SECURITY profiles for jobs such as
FULLDUMP,MANAGER.SYS, COMPALL,MGR.AP, etc.  We believe that this will give you
a maximum of system security AND ease of operation.

A couple of other points -- first of all, note that when we specified
$BATCH-VEPROFILE in our examples, we said

   $BATCH-VEPROFILE @.@

This means that all users (who also have $VEPROFILE set) have their SECURITY
passwords (and other SECURITY user profile security items) work both online and
offline.  You could specify some other userset, e.g.

   $BATCH-VEPROFILE @.@-STREAM.AP-STREAM.GL

This means that the users STREAM.AP and STREAM.GL will not have their SECURITY
user profiles take effect in batch.  You might, for instance, protect these
users with MPE passwords and not want to have to stream all their jobs through
STREAMX.

Another feature we give you is the ability to disallow batch access by certain
users altogether.  For instance, you can say


NO-BATCH, SECURCON file keyword ``batch
$NO-BATCH, SECURCON file keyword

   $NO-BATCH @.AP-STREAM.AP-COMPILE,@.AP

which means that no jobs can log on to the AP account except for those that log
on with user ID STREAM or session name COMPILE.  This can be a viable
alternative to $BATCH-VEPROFILE in some cases; you can just impose
$BATCH-VEPROFILE or MPE passwords on some users, and forbid all job submissions
under most user IDs.

Remember though -- whether you use $BATCH-VEPROFILE or MPE passwords, you must
use something to protect your system against unauthorized batch (as well as
online) access.  To summarize, you can do this by using one of the following
methods:

   - Using $BATCH-VEPROFILE;

   - Prohibiting all batch access for some users using $NO-BATCH;

   - Prohibiting all batch access to some MPE user IDs by taking BA capability
     away from them; VEAUDIT users can do this by saying something like:

        %VEAUDIT ALTUSER @.MYACCT-JOBUSER.MYACCT;CAP=-BA

   - Securing the rest of your users using MPE passwords.

MPE PASSWORD EXPIRATION (OBSOLESCENCE)


MPE password maintenance ``contents
MPE password maintenance
MPE password expiration
$MPE-OBSOL, SECURCON file keyword

The same considerations that require periodic changes of SECURITY passwords
also require periodic changes of MPE passwords (if you use them).  The longer a
password remains unchanged, the more likelihood there is that the password will
become more and more widely known, and thus become useless.  The only way to
prevent this is to require periodic changes of passwords, preferably by the
users themselves (without intervention by an account manager).

With SECURITY, this is very easy -- all you need to do is to add to the
SECURCON file the line:

   $MPE-OBSOL [usersets]

where each "userset" indicates who is to have his MPE passwords obsoleted (i.e.
automatically expired).  You could, for instance, say

   $MPE-OBSOL @.@

which simply means everybody will have their passwords automatically expired.
Alternatively, you might say

   $MPE-OBSOL @.AP @.PROD

which means "automatically expire all passwords in the AP account and in the
PROD account" or

   $MPE-OBSOL @.AP-BATCH.AP CAP=SM CAP=PM

which means "automatically expire all passwords for AP users (except for the
user BATCH.AP) and also for all users who have either SM or PM capability".
(As you see, each "userset" can be a very powerful entity -- for more
information on them, see the Usersets chapter.)

What exactly does this password expiration do? Well, SECURITY keeps track of
every time a password is changed.  Every time a user logs on, SECURITY checks
to see:

   * if he has an MPE user password;

   * if the password has been changed in the last 30 days;

If the user has a password but it has not been changed in the last 30 days, the
user gets a message that looks something like this:

   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

   Your user password has expired!

   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

   Please type your current user password:    << user types password >>

   Please type your new user password:

The user must now enter a new password (one that is different from the one he
had before).  He won't be allowed to log on until he enters this password; when
he does enter it, his MPE user password will automatically be changed to this
new value.  (With the MPE Password History feature we talk about below, you can
even make certain that the password is different from all the passwords he's
used in the last, say, 6 months or a year.)

Thus, at logon time we make sure that a password is no older than 30 days, and
if it is, we force the user to change it.  Note that we're not saying that
every 30th day, all system passwords must be changed at once; rather, a
password must be changed after it has been in effect for longer than 30 days --
if one password was last changed on November 1st and another on November 15th,
then the first will expire on December 1st and the second on December 15th.

Of course, though 30 days is the default expiration period, you can very easily
configure a different one.  For instance, you can say (in the SECURCON file):


MPE-U-OBS-DAYS, SECURCON file keyword ``expire`user
$MPE-U-OBS-DAYS, SECURCON file keyword

   $MPE-OBSOL @.AP @.PROD
   $MPE-U-OBS-DAYS 20

which simply means that all users in the AP and PROD account will have their
passwords expired after 20 days.  Alternatively, you could say

   $MPE-OBSOL @.AP @.PROD
   $MPE-U-OBS-DAYS 30 @.AP
   $MPE-U-OBS-DAYS 45 @.PROD-MGR.PROD
   $MPE-U-OBS-DAYS 20 MGR.PROD

This indicates that AP users will have their passwords expire every 30 days,
PROD users (except for MGR.PROD) will have theirs expire every 45 days, and
MGR.PROD's password will expire every 20 days.

As you see, the principle here is:

   * The password expires after some number of days;

   * Once it's expired, the user is forced to change it.

There are, however, other alternatives that you might want to use.  For
instance, you might not want to let a user log on after his password has
expired, even if he's willing to change the password.  If a password has not
been changed within the specified expiration period, you might treat that as an
exceptional circumstance and want to force the user to go to his account
manager and have his account manager change the password.  You can do that by
simply adding the line


MPE-OBS-PASSCHG, SECURCON file keyword ``expire`change
$MPE-OBS-PASSCHG, SECURCON file keyword

   $MPE-OBS-PASSCHG OFF

to your SECURCON file; alternative, by adding the line

   $MPE-OBS-PASSCHG @.AP

you can indicate that your AP users will be prompted for a new password when
their old one expires, but your other users will have to go to their account
managers.  Note that all users can still change their own passwords by saying

   :RUN MAIN.PUB.VESOFT,PASSWORD

or using the UDC (which we define in our LOGONUDC.PUB.VESOFT file) called

   :PASSWORD

The $MPE-OBS-PASSCHG keyword simply controls whether or not you want to allow
people to change their passwords after they have been automatically obsoleted.

If you do decide to forbid users to log on at all after their passwords expire,
you'll usually want to have some way of warning them when the password is about
to expire.  You can do this by saying:


MPE-U-WARN-DAYS, SECURCON file keyword ``warning`user
$MPE-U-WARN-DAYS, SECURCON file keyword

   $MPE-U-WARN-DAYS 7

   or

   $MPE-U-WARN-DAYS 7 @.AP
   $MPE-U-WARN-DAYS 5 @.PROD

This simply means that 7 (or, in the second example, either 7 or 5) days before
a password will expire, the user will be told at logon time that expiration
will soon occur.  You can also use the $MPE-WARN-PASSCHG keyword:


MPE-WARN-PASSCHG, SECURCON file keyword ``warning`change
$MPE-WARN-PASSCHG, SECURCON file keyword

   $MPE-WARN-PASSCHG @.@

   (or just $MPE-WARN-PASSCHG @.AP if you only want to turn it on for AP
    account users)

to indicate that during the warning period, the user is to be prompted for a
new password (as opposed to the default, in which the user is prompted for a
new password only after the old one expires).  Thus, your SECURCON file might
include the lines:

   $MPE-OBSOL @.AP @.PROD
   $MPE-OBS-DAYS 30
   $MPE-OBS-PASSCHG OFF
   $MPE-WARN-DAYS 7 @.AP
   $MPE-WARN-DAYS 5 @.PROD
   $MPE-WARN-PASSCHG @.@

This indicates that:

   * all AP and PROD account users ($MPE-OBSOL @.AP @.PROD) will have their
     passwords obsoleted every 30 days ($MPE-OBS-DAYS 30);

   * once a password is obsolete, a user won't have a chance to change it, but
     will rather have to go to his account (or system) manager
     ($MPE-OBS-PASSCHG OFF);

   * however, some number of days (7 for AP users and 5 for PROD users) before
     expiration ($MPE-WARN-DAYS), the user will be given a warning message and
     will be asked to enter a new password ($MPE-WARN-PASSCHG @.@).

Note that if $MPE-WARN-PASSCHG is on and the user is prompted for a new
password during the WARNING PERIOD, the user can always hit control-Y and log
on without changing his password.

However, if $MPE-OBS-PASSCHG is on and he is prompted for a new password when
the old one is already obsolete, he won't be allowed to log on until he enters
a new password.


MPE-A-OBS-DAYS, SECURCON file keyword ``expire`account
$MPE-A-OBS-DAYS, SECURCON file keyword
$MPE-A-WARN-DAYS, SECURCON file keyword
$MPE-G-OBS-DAYS, SECURCON file keyword
$MPE-G-WARN-DAYS, SECURCON file keyword
, SECURITY also lets you obsolete account and group passwords, too.  By
default, they're not obsoleted (since group passwords are rare and account
passwords are often shared by too many people to be feasibly changed
periodically).  However, if you want to, you can easily say

   $MPE-A-OBS-DAYS 120 @.@-@.TELESUP
   $MPE-A-WARN-DAYS 10
   $MPE-G-OBS-DAYS 45 @.DEV @.SYS
   $MPE-G-WARN-DAYS 5 @.DEV

This will indicate that all account passwords (except for the TELESUP password)
are to be obsoleted every 120 days, with a 10-day warning period; all group
passwords in the DEV and SYS accounts are to be obsoleted every 45 days, with a
5-day warning period on group passwords in DEV and no warning period on the
other group passwords.

Note that because of the different nature of account and group passwords, a
user will not be automatically prompted for a new password either after the old
one has expired or during the warning period.  It is the system manager's or
account manager's job to change the passwords when necessary.

To summarize, the various MPE obsolescence-related options include:


MPE-WARN-DAYS, SECURCON file keyword
$MPE-WARN-DAYS, SECURCON file keyword
$MPE-OBS-DAYS, SECURCON file keyword

$MPE-OBSOL usersets                Enable password obsolescence for the given
                                userset(s).
$MPE-OBS-DAYS numdays [usersets]   Set password lifetime for all MPE passwords
                                (account, group, and user).
$MPE-WARN-DAYS numdays [usersets]  Set warning period for all MPE passwords
                                (account, group, and user).
$MPE-U-OBS-DAYS numdays [usersets] Set MPE user password lifetime (default 30).
$MPE-U-WARN-DAYS numdays [usersets] Set warning period for MPE user passwords
                                (default none).
$MPE-OBS-PASSCHG [usersets]        Allow passwords to be changed upon
                                obsolescence for only the given usersets
                                (default @.@).
$MPE-WARN-PASSCHG [usersets]       Allow passwords to be changed during warning
                                period for the given usersets (default none).
$MPE-A-OBS-DAYS numdays [usersets] Set account password lifetime (default:
                                account passwords never expire).
$MPE-A-WARN-DAYS numdays [usersets] Set account password warning period
                                (default none).
$MPE-G-OBS-DAYS numdays [usersets] Set group password lifetime (default: group
                                passwords never expire).
$MPE-G-WARN-DAYS numdays [usersets] Set group password warning period (default
                                none).
$MPE-PASSHIST-DAYS numdays [usersets] Set password history period (see "MPE
                                Password History").

To accommodate MPE password obsolescence, you must execute the OBSFILL task
under the BACKG job every night; to have it run, use the command

   %SEC BACKG STARTJOB        (* If it's not already running *)
   %SEC BACKG START,OBSFILL

(Please see %BACKG in the MPEX Commands chapter of the MPEX User Manual for
details.) OBSFILL collects information on what password changes were made the
previous day.  By default, it runs at 01:00 (1:00 AM), but you may change this
by adding the line

   SETVAR OBSFILLTIME "time"

(where "time" is the time you want OBSFILL to execute) to the
BACKGINI.DATA.VESOFT file, as explained in the "%BACKG" documentation mentioned
above.

MPE PASSWORD HISTORY


MPE password history ``contents
MPE password history
$MPE-PASSHIST-DAYS, SECURCON file keyword
$MPE-PASSHIST-DAYS, SECURCON file keyword

Just like the SECURITY PASSWORD HISTORY feature prevents users from reusing
their old SECURITY passwords for a given amount of time (e.g.  6 months or a
year), so the MPE PASSWORD HISTORY feature prevents users from reusing their
old MPE passwords for a given time.  For instance, you can say:

   $MPE-PASSHIST-DAYS 180

(which indicates that nobody can reuse any password twice in a 180-day period)
or

   $MPE-PASSHIST-DAYS 180 @.PROD
   $MPE-PASSHIST-DAYS 365 OPERATOR.SYS PETE.AP

(which indicates that the PROD account users can't reuse theirs for 180 days,
OPERATOR.SYS and PETE.AP can't reuse theirs for 365 days, and everybody else
does not have any restriction on password reuse).  SECURITY will remember the
passwords each user has used in the past, say, 180 or 365 days, and will make
sure that his new password is different.

For instance, say a user logs on, SECURITY detects that his MPE password will
soon be obsoleted, and prompts him for a new one:

   :HELLO OLIVER.PROD
   ENTER USER (OLIVER) PASSWORD:    << user types password >>

   **********************************************************

   Your user password will expire in 7 days!

   **********************************************************

   Please type your current user password:    << user types password >>
   Please type your new user password:    << user types new password >>
   Please type your new user password again:    << types it again >>

   Error: You may not reuse passwords for 180 days.

   Please type your new user password again:    << types it again >>
   Please type your new user password again:    << types it again >>
     << User has entered an entirely new password, everything's OK >>
   Welcome!  You are now signed on.

Note that this applies only when a user changes his password through SECURITY
-- either at warning or expiration time or using the MAIN.PUB.VESOFT,PASSWORD
entry point (or the :PASSWORD UDC).  If an account or system manager changes a
user's password using the :ALTUSER command, SECURITY can do nothing because it
is not involved in the password change.  On the other hand, this is usually not
a problem -- after all, if an account or system manager sets a new password, he
probably knows what he's doing; it's the individual users changing their own
passwords that you ought to watch out for.

ENFORCING MPE PASSWORD STANDARDS (E.G.  MINIMUM LENGTH)


Enforcing MPE password standards ``contents
Enforcing MPE password standards
Password standards: MPE passwords
Minimum password length: MPE passwords
$MPE-PASS-EDIT, SECURCON file keyword

Even if you force users to have passwords, they'll often (through laziness and
complacency) make them quite inadequate for system security.  Often, they'll
make them only one or two characters, making it easy for people to guess them
(and figure them out by looking at the user's fingers while he's typing them
in); or, they'll use obvious passwords, like their names or their spouses'
names or something like that.

The $MPE-PASS-EDIT facility lets you avoid this problem.  It lets you set up an
MPE-fileset-like password edit mask that indicates which password formats are
acceptable and which are not.  For instance, you can put into your
SECURCON.DATA.VESOFT file the line:

   $MPE-PASS-EDIT "????@"

This edit mask indicates that each password must be 4 characters followed by
any number of characters -- in other words, must be at least 4 characters long.
Any time a user specifies a password for himself (at password expiration time
or using the :RUN MAIN.PUB.VESOFT,PASSWORD facility that we provide), his
password will be checked -- if it's less than 4 characters long, it'll be
rejected and a different one will be asked for.

Say, for instance, the user types :PASSWORD:

   :PASSWORD

   SECURITY/PASSWORD 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

    Please type your current user password:     << no echo >>

    Please type your new user password:         << user types "X" >>
    Please type your new password again:        << user types "X" >>

    Error: Password must match system standards.

    Please type your new user password:

What about preventing easy-to-guess passwords like the user's last name or
nickname or something like that? Well, unfortunately the computer can't tell
what a password really means and whether it is obvious or not.  One thing you
can do is simply require that each password contain a digit (some standards
require this).  This way, whatever the password is, it won't be anywhere near
as easy to guess as one that is entirely alphabetic.

For instance, one possible SECURCON.DATA.VESOFT configuration might thus be:

   $MPE-PASS-EDIT "???@#" @.DEV @.PROD
   $MPE-PASS-EDIT "?????@#" @.AP @.GL
   $MPE-PASS-EDIT "?#?#?@" CAP=SM CAP=PM

This simply means that:

   * All DEV and PROD account users must have a password that's at least four
     characters long and the last character is a digit;

   * All AP and GL account users must have a password that's at least six
     characters long and the last character is a digit;

   * All users that have SM or PM capability must have a password that's at
     least five characters long, with both the second and the fourth characters
     being digits;

   * All other users can have any password they want.

FLEXIBLE MPE USER PASSWORD EDIT CHECKING


Flexible MPE USER password edit checking ``contents
Flexible MPE USER password edit checking
$MPE-PASS-FORBID, SECURCON file keyword
P, SECURCON expression variable for MPE password edit checking

The $MPE-PASS-FORBID keyword (syntactically identical to the $VEPASS-FORBID
keyword; see "Flexible SECURITY Password Edit Checking", above) lets you impose
arbitrary edit checks on MPE passwords.

The syntax of this keyword is:

   $MPE-PASS-FORBID "expression" "error message" [usersets]

which means "forbid people from setting up MPE user passwords that match the
given expression; if such a password is tried, print the given error message".
As with $VEPASS-FORBID, the special variable P contains the value entered by
the user.

If you don't specify a userset, the restriction will apply to all users
whenever they try to change their MPE user password through SECURITY (via
LOGON,PASSWORD, %SEC PASSWORD or when prompted to by our MPE password
obsolescence facility).

Here are a few examples:

   $MPE-PASS-FORBID "ALPHA(P)" "Password must not be only alphabetic"

   $MPE-PASS-FORBID "NUMERIC(P)" "Password must not be only numeric"

   $MPE-PASS-FORBID "POS('Q',P)<>0 or POS('Z',P)<>0"
      "Password may not contain Qs or Zs"

   $MPE-PASS-FORBID "MAXCONSECUTIVE(P)>=3"
      "Password may not contain 3 or more consecutive identical chars"

   $MPE-PASS-FORBID "P=HPUSER or P=HPACCOUNT or P=HPHGROUP"
      "Password may not match your user, account or home group name"

   $MPE-PASS-FORBID "P=VEACCTINFO(HPACCOUNT).PASSWORD"
      "Password may not be the same as your MPE account password"

   $MPE-PASS-FORBID "P=VEGROUPINFO(HPHGROUP+'.'+HPACCOUNT).PASSWORD"
      "Password may not be the same as your MPE home group password"

   $MPE-PASS-FORBID "BADPASSWORD(P)" "Password is too easy to guess"

ENSURING THAT ALL USERS HAVE MPE PASSWORDS


Ensuring that all users have MPE passwords ``contents
Ensuring that all users have MPE passwords
$MPE-U-NEED-PASS, SECURCON file keyword
$MPE-U-NEED-PASS, SECURCON file keyword

SECURITY can let you make sure that all users (or all users in a particular
account or a particular userset) have MPE passwords.  Although when a user
changes his own MPE password using SECURITY, he won't be allowed to remove it
(only change it), you might be concerned that, either by accident or from
laziness, your account or system manager might forget to initially configure a
user with a password in the first place.

The keyword you need to use for this is:

   $MPE-U-NEED-PASS [usersets]

For instance,

   $MPE-U-NEED-PASS @.SYS CAP=SM CAP=PM

indicates that

   * all users in the SYS account

   * and all users with SM capability

   * and all users with PM capability

must have user passwords.  If they don't have a password, they won't be allowed
to log on until their account or system manager :ALTUSERs them to have a
password.  Actually, the example we gave above is very useful practically -- we
recommend that you at least say

   $MPE-U-NEED-PASS CAP=SM CAP=PM

to make sure that you don't inadvertently have an non-passworded SM or PM user.

ALLOWING USERS TO CHANGE THEIR OWN MPE USER PASSWORD


Allowing users to change their own MPE user password ``contents
Allowing users to change their own MPE user password
:PASSWORD, UDC used by users to change their password
PASSWORD, MAIN.PUB.VESOFT entry point

At first glance, letting a user change his own password may not seem like a
security feature (after all, it would appear that the more people can change
passwords, the less secure the system is).  However, we believe that this
ability is indispensable to your MPE password security.

Passwords are only good if they're frequently changed; MPE's :ALTUSER
restriction that only the account or system manager can change a user's
password serves as a strong disincentive to change passwords.  If there are
fifty users in an account, how likely is the account manager to change all
fifty passwords periodically?

It's much better to let users change their own passwords.  This way you can
easily require them, for instance, to change their passwords every month (e.g.
with our automatic password expiration facility).  The burden of changing all
the passwords -- too much for a single account manager -- can be easily borne
by each individual user.

SECURITY lets a user change his MPE user password under three conditions:

   * When password expiration is turned on, the password has expired, and the
     user is trying to log on.  In this case, the user won't be permitted on
     the system until he enters a new password.

   * When password expiration and the pre-expiration warning ($MPE-U-WARN-DAYS)
     are both set and the user is trying to log on during the warning period.

   * When a user explicitly asks to change his password by saying

       :RUN MAIN.PUB.VESOFT,PASSWORD

     or by using the UDC :PASSWORD (which does exactly the just-mentioned :RUN
     command) that we provide in our LOGONUDC.PUB.VESOFT file.  (If you don't
     want to give a user full MPE access, you can specify an option to change a
     password in a user's SECURITY logon menu file.)

     MPEX users can do the same thing by saying (within MPEX):

       %SEC PASSWORD

NOTE: the %SEC PASSWORD changes the MPE password, not the SECURITY password.
You should use the %SEC VEPASSWORD command to change a user's SECURITY
password.  See the chapter Command-driven SECURITY Maintenance for details on
using the %SEC commands.

If you don't want to let a user change his own password, you can turn this
capability off:

   * To prevent changes at expiration and warning time, you can use the
     $MPE-OBS-PASSCHG OFF and $MPE-WARN-PASSCHG OFF keywords (see above).


ALLOW-MPE-PASSCHG, SECURCON file keyword
$ALLOW-MPE-PASSCHG, SECURCON file keyword

  * To prevent a user from running the PASSWORD entry point (or using %SEC
     PASSWORD), you can say (in the SECURCON file):

        $ALLOW-MPE-PASSCHG OFF

     or, to allow only some users to run the PASSWORD entry point, you can say

        $ALLOW-MPE-PASSCHG @.AP @.PROD

     (which will, of course, allow the PASSWORD entry point to be used only by
     the users in the AP and PROD accounts).

However, we would recommend that you permit everybody to change their own
passwords, and encourage them to do this as often as possible.  Of course, you
needn't be concerned about changing all the MPE passwords in job streams, since
our STREAMX module completely eliminates the need for embedded passwords.

DEACTIVATING PROFILES AFTER UNSUCCESSFUL LOGON ATTEMPTS


Deactivating profiles after unsuccessful logon attempts ``contents
Deactivating profiles after unsuccessful logon attempts
$VE-DEACTIVATE, SECURCON file keyword

Sometimes, would-be security violators will find some user ID and "attack" it,
trying to guess its password many times until they finally, by accident, hit
the right one.  SECURITY lets you automatically deactivate any profile that has
had more than a certain number of consecutive unsuccessful logon attempts.
This profile will then be completely unusable until the account or system
manager specially reactivates it (i.e.  no one will be able to log on using
it).

You can do this by adding to your SECURCON.DATA.VESOFT file the line

   $VE-DEACTIVATE 5

or, if you want to, something more sophisticated, such as

   $VE-DEACTIVATE 2 @.UTIL CAP=SM CAP=PM CAP=OP
   $VE-DEACTIVATE 3 @.PAYROLL-INQUIRE.PAYROLL
   $VE-DEACTIVATE 5 INQUIRE.PAYROLL

The three lines above -- a good example of the power of the SECURITY
configuration options -- indicate that:

   * any SECURITY user ID that is used to log on to the UTIL account or any
     user with SM, PM or OP capability will be automatically deactivated after
     2 consecutive unsuccessful logon attempts;

   * any SECURITY user ID belonging to the PAYROLL account (except those for
     the MPE user INQUIRE.PAYROLL) will be automatically deactivated after 3
     consecutive unsuccessful logon attempts;

   * any SECURITY user ID that is used to log on as INQUIRE.PAYROLL will be
     automatically deactivated after 5 consecutive unsuccessful logon attempts;

   * any other SECURITY user ID -- one not in the UTIL or PAYROLL accounts and
     not for an SM, PM or OP user -- will not be deactivated regardless of the
     number of consecutive unsuccessful logon attempts.

In the above example, say that somebody tries to log on as JACK,TEST.UTIL.

The first time, SECURITY will give him two chances (this number may be changed
using the $VE-NUM-TRIES keyword) to specify his SECURITY password; if he gives
the wrong password both times, he'll be logged off.  The second time, SECURITY
will again give him two chances to specify his password.

If he fails the second time, SECURITY will log him off and deactivate the user
ID "JACK,TEST.UTIL".  If he tries to log on again, SECURITY won't even prompt
him for his passwords -- it'll just log him off automatically because the user
ID is deactivated.

Note: if the user "times out" (i.e.  fails to enter his password before the
number of seconds specified by $VE-TIMEOUT) this will also be counted as an
invalid logon attempt.

A user ID can only be reactivated by the account or system manager.  To do
this, he would say:


REACTIVATE, MAIN.PUB.VESOFT entry point

   :RUN MAIN.PUB.VESOFT,REACTIVATE

   SECURITY/REACTIVATE 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type
'HELP'

   Enter user ID: TEST
   Enter account: UTIL
   Enter session name: JACK
   *** User has been reactivated ***

Now, the user has been reactivated.  JACK,TEST.UTIL can log on again, at least
until the next time he fails two logon attempts in a row.

Several things need to be noted about SECURITY user deactivation:

   * SECURITY user profiles -- not MPE users -- are deactivated.  This way, if
     somebody's trying to "attack" the user ID JACK,TEST.UTIL, then
     JOHN,TEST.UTIL would still be able to log on -- only JACK,TEST.UTIL, the
     SECURITY user ID whose passwords are being incorrectly specified, is
     deactivated.

   * The only unsuccessful logons that count towards deactivation are those in
     which the user entered the wrong SECURITY passwords.  If he's trying to,
     for instance, violate terminal, day-of-week, or time-of-day access
     restrictions, he won't get deactivated, since those restrictions are
     absolute and can't be avoided by repeated tries (remember, the purpose of
     user deactivation is to avoid attempts to guess passwords).

     If you're using both MPE and SECURITY passwords for the same user, invalid
     MPE password entries won't count towards deactivation either, since MPE
     will reject them before SECURITY will get a chance to intervene.

   * Deactivation happens after a given number of consecutive unsuccessful
     logon attempts.  Any successful logon for a particular user ID
     automatically resets the "consecutive unsuccessful logon attempt counter".

   * Finally, for a related feature that lets you deactivate the LDEV on which
     the violation occurred (not just the user ID for which it occurred), see
     the chapter on Deactivating Terminals After Unsuccessful Logon Attempts.

DEACTIVATING TERMINALS AFTER UNSUCCESSFUL LOGON ATTEMPTS


Deactivating terminals after unsuccessful logon attempts ``contents
Deactivating terminals after unsuccessful logon attempts

A large number of consecutive unsuccessful logon attempts -- especially over a
dial-in line -- may indicate an attack on your system security.  Somebody may
be trying passwords at random until they find one that works.  Many audit
standards require protection from this type of break-in attempt.


TERM-DEACTIVATE, SECURCON file keyword ``terminal`deactivate
$TERM-DEACTIVATE, SECURCON file keyword
adding a line to your SECURCON.DATA.VESOFT file that says something like:

   $TERM-DEACTIVATE 5

you tell SECURITY that after 5 consecutive unsuccessful logon attempts on any
given terminal, that terminal will be :DOWNed.  This means the terminal will be
completely unusable -- a user won't even get a : -- until the console operator
executes an :UP command for it.

You may want to specify more of this security for some devices or some logons
than for others.  To do this, you'd put one or more usersets (see below) after
the "$TERM-DEACTIVATE <number>" -- the $TERM-DEACTIVATE will then apply only to
users in these usersets.  Since a userset can select users by name or by the
terminal on which they're logging on, you might put into your SECURCON file the
lines

   $TERM-DEACTIVATE 2 LDEV=61 LDEV=62
   $TERM-DEACTIVATE 5 LDEV=70 LDEV=72 LDEV=73
   $TERM-DEACTIVATE 1 @.SYS-OPERATOR.SYS

The above lines specify that:

  * LDEVs 61 and 62 are to be shut down after 2 consecutive unsuccessful logon
    attempts;

  * LDEVs 70, 72, and 73 are to be shut down after 5;

  * if anybody unsuccessfully tries to log on into the SYS account (except
    OPERATOR.SYS), his terminal will be shut down immediately (after 1
    attempt);

  * and all other people won't have their terminals shut down at all.

Finally, note that an "unsuccessful logon attempt" includes an incorrect
specification of

   * a terminal password

   * or a SECURITY password.

It does not include incorrect user IDs, bad MPE passwords, logon attempts at
unauthorized days of week or times of day, etc.

Furthermore, as soon as there is one successful logon, the unsuccessful attempt
counter is reset to 0 -- only consecutive unsuccessful logon attempts actually
cause terminal deactivation.

NOTE: in order for this keyword to function properly, your $PASS prompt must
      read "TERMINAL PASSWORD" in upper case.

RESTRICTING WHO MAY LOG ON WHERE, WHEN AND HOW

   -- A GENERAL SOLUTION ($FORBID)


Restriction who may log on -- a general solution ($FORBID) ``contents
Restriction who may log on -- a general solution ($FORBID)


FORBID, SECURCON file keyword ``restrictions
$FORBID, SECURCON file keyword
addition to the many special-purpose logon restrictions -- terminal
restrictions, time-of-day restrictions, day-of-week restrictions, $SESS-EDIT,
$NO-CONCUR-SESS -- SECURITY has a very powerful general-purpose log on
restriction.  It lets you forbid logons by anybody who matches an arbitrary
logical expression, one which can (very flexibly) select by logon ID, time,
day, and many other conditions.

Before we discuss the exact syntax of this facility (implemented by the $FORBID
keyword in the SECURCON.DATA.VESOFT file), here are a few examples:


FORBID, examples
$FORBID, examples

   $FORBID "HPLDEVIN=20" "Error: Don't log on to the console" @.DEV

   $FORBID "NOT BETWEEN(HPLDEVIN,50,70)" "Error: Bad terminal" @.AP

   $FORBID "JSCOUNT('@.AP&ONLINE')>10"
             "Error: Only 10 AP sessions allowed at a time" @.AP&ONLINE

   $FORBID "JSCOUNT('PARTBACK,MANAGER.SYS&EXEC')>0"
             "Warning: system backup in progress - try again later"
             @.@-GAMEPLR.CSL3000-PARTBACK,MANAGER.SYS

   $FORBID "NOT BETWEEN(CLOCK,7:45AM,5:15PM)"
             "Error: Bad time" @.AP-MANAGER.AP @.GL-JOE,@.GL

These examples:

   * prohibit any logons on LDEV 20 by users in the DEV account;

   * prohibit logons on any devices other than 50 through 70 by AP account
     users;

   * prohibit logons to the AP account whenever there are already more than 10
     sessions (including the person logging on) logged on to that account;

   * prohibit logons at any time except 7:45 AM through 5:15 PM by any users in
     the AP account (except MANAGER.AP) and the GL account (except any user
     with session name JOE).

The first parameter to the $FORBID keyword is an arbitrary logical expression.
The exact syntax of these expressions is discussed in the Appendix to this
manual; you have available to you hundreds of different operators (=, <, AND,
OR, etc.), functions (BETWEEN, JSCOUNT, etc.), and variables (HPACCOUNT,
HPJOBNAME, HPLDEVIN, etc.) to specify exactly under which conditions you want
to forbid a logon.  In addition, you also have access to all of the "User
Profile Attribute Variables And Functions" listed in the the "Listing User
Profiles" chapter, above.

The second $FORBID parameter is the error message to be output to the user who
matches the expression.  Before he is logged off, this message will be output
to his terminal; you can be as clear or as vague (for security reasons) as you
like.  The error message is also included in the SECURITY console message;
additionally, the first 30 characters of the message are put into the log file
record that's logged as a result of the logon rejection.

After the first two parameters come the usersets to whom this $FORBID keyword
is to apply.  Our first example, for instance ($FORBID "HPLDEVIN=20" ...
@.DEV) prohibits only DEV account users (@.DEV) from logging on to LDEV 20;
this gives you even more flexibility and control.

(Note that $FORBIDs can apply to both jobs and sessions -- if you want it to
apply only to jobs or only to sessions, you can use the "&BATCH" or "&ONLINE"
options of the userset parameter, e.g.

   $FORBID "NOT BETWEEN(CLOCK,7AM,5:15PM)" "Error: Bad time" @.AP&ONLINE

will apply the time restrictions only to AP account sessions.)

Here are a few ideas about what you can do with $FORBID:


Terminal restrictions, $FORBID as an alternative

  * Be very flexible in specifying terminal, time-of-day, and day-of-week
     restrictions (more so than you can be with :RUN MAIN.PUB.VESOFT,ADD);

          $FORBID "NOT BETWEEN(HPLDEVIN,50,70)" ...  ...

     lets you restrict a user to a range of terminals (50 through 70), not just
     to a list of terminals.  Similarly,


Time-of-day restrictions, $FORBID as an alternative
Day-of-week restrictions, $FORBID as an alternative

          $FORBID "NOT BETWEEN(CLOCK,7:45AM,5:15PM)" ...  ...

     lets you specify time-of-day restrictions to the minute (not just to the
     hour); also, you can say

          $FORBID "HPDAY=6 and BETWEEN(CLOCK,4:30PM,5:15PM)" ...  ...

     to specify time-of-day restrictions applying only to a particular day of
     the week (here day 6 or Friday).

   * Impose terminal restrictions, time-of-day restrictions, and day-of-week
     restrictions not just on individual users (as you can when doing a :RUN
     MAIN.PUB.VESOFT,ADD) but on entire usersets, e.g.

          $FORBID "HPLDEVIN=20" "..." @.DEV

          $FORBID "NOT BETWEEN(CLOCK,7:45AM,5:15PM)" "..."
                    @.AP-MANAGER.AP @.GL-JOE,@.GL

   * Say


SESS-EDIT, $FORBID as an alternative
$SESS-EDIT, $FORBID as an alternative

          $FORBID "NOT (HPJOBNAME MATCHES '???###' or &
                        HPJOBNAME MATCHES '???####')" ...  ...

     to impose not just a single edit mask on session names (which you could do
     with $SESS-EDIT) but two or more;


NO-CONCUR-SESS, $FORBID as an alternative
$NO-CONCUR-SESS, $FORBID as an alternative
Concurrent sessions, restricting them

          $FORBID "JSCOUNT('ONLINE&@.'+HPACCOUNT)>10" ...  @.@

     to impose a limit of at most 10 sessions per account (see the
     documentation of the JSCOUNT function in Appendix for more information);


Console intervention, requiring it to log on

          $FORBID "PRINTOPREPLY('ALLOW TELESUP LOGON (Y/N)? ')<>'Y'"
                  "Operator forbade logon!" @.TELESUP

     to ask the console operator for permission before allowing anybody to log
     on to the TELESUP account (see the documentation of the PRINTOPREPLY
     function in Appendix);

          $FORBID "FEXISTS('NOLOGON.PUB')"
                  "Account access temporarily disabled!" CAP<>AM

     to forbid any non-AM users to log on to an account in which there exists a
     NOLOGON.PUB (which lets you easily temporarily disable access to an
     account, for instance when you're changing some important files in that
     account).

The only limitation here is your own imagination -- and the extent to which you
read Appendix, which will help you learn about useful operators, functions, and
variables that you might otherwise have never heard of.

Special notes:

   * During the evaluation of the first parameter of $FORBID the capability
     mask of the user is temporarily modified.  Thus, you should not use the
     CAPABILITY(S) function in this expression since it will not reflect the
     user's real capabilities.  If you want to select users based on their
     capabilities, use the CAP=xxx syntax in the userset.

     For example, to prohibit SM or PM logons on devices 62, 64 or 67
     (presumably dial-in lines) except for logons to the TELESUP account (which
     we hope you've properly secured!), you should use something like:

          $FORBID "ACCOUNT<>'TELESUP'"
             "Sorry, no SM/PM logons allowed on dial-in lines!"
             (LDEV=62+LDEV=64+LDEV=67)&(CAP=SM+CAP=PM)

      rather than

          $FORBID "CAPABILITY('SM') or CAPABILITY('PM')"
             "Sorry, no SM/PM logons allowed on dial-in lines!"
             LDEV=62+LDEV=64+LDEV=67-@.TELESUP

   * Also, if several $FORBIDs apply to a particular logon, all the $FORBID
     conditions will be checked, and the user will be logged off if he matches
     any one of them.

   * Finally, if you want to continue the $FORBID expression onto a new line,
     just put an & at the end of the line to be continued, e.g.

        $FORBID "NOT (HPJOBNAME MATCHES '???###' or &
                 HPJOBNAME MATCHES '???####')" ...  ...

Closing the NEGATIVE ;PARM= loophole


CLOSING THE NEGATIVE ;PARM= LOOPHOLE``contents
CLOSING THE NEGATIVE ;PARM= LOOPHOLE
Using HELLO trap for LOGON SECURITY

HP's AIF:PE product allows a software developer to intercept all calls to a
particular system intrinsic or routine.  We have created an AIF:PE procedure
called HELLO which intercepts all attempts to logon to an HP3000 system,
including all jobs, sessions, network-originated logons and auto-logons.

When HELLO trap intercepts the logon command, it inspects the :HELLO string for
negative ;PARM= values and can strip them out at this time.

Depending upon how you have configured our software, this trap will either
strip out all negative ;PARM= values from the LOGON string or only those values
you have inhibited.  This closes the loophole where interactive SM users can
bypass execution of logon UDCs when logging on.

Other benefits of HELLO trap


Other benefits of HELLO trap``contents`news
Other benefits of HELLO trap

HELLO trap also allows us to implement the following new features.  These
features are all optional, and are only available if configured in the
HELLO.DATA.VESOFT file.

- HELLO synonyms.


HELLO synonyms``contents`news
HELLO synonyms

It is possible to define synonyms for the HELLO command, for example 'HI'.
This feature is only available to users logging on interactively.  Multiple
synonyms may be defined, if required.

You can also redefine the HELLO command itself so that users can only logon via
a HELLO synonym, and not by using HELLO directly.

Refer to the description of the $CHANGE keyword in the 'Configuring HELLO trap'
section for more information.

- UNIX-style logons.


UNIX-style logons``contents`news
UNIX-style logons

  It is possible to allow users to logon simply by entering their name, without
  requiring that it be prefixed by HELLO or even by a HELLO synonym.  This
  feature is only available to users logging on interactively.

  Refer to the description of the $ASSUME-HELLO keyword in the 'Configuring
  HELLO trap...' section for more information.

- Abbreviated logons.


Abbreviated logons``contents`news
Abbreviated logons

  It is possible to define abbreviated logon strings, for example 'TONY' could
  be treated as equivalent to 'ANTHONY,OPERATOR.SYS,OPERATOR'.  This feature is
  available to users logging on interactively, as well as for network
  originated logons.  It is not accessible from jobs.

  Refer to the description of the $HELLO keyword in the 'Configuring HELLO
  trap...' section for more information.

- Disallowing embedded MPE passwords.


Disallowing embedded MPE passwords``contents`news
Disallowing embedded MPE passwords

  You may specify that any attempt to log on interactively with embedded MPE
  passwords in the logon command should be disallowed.  You may configure the
  HELLO task to remove embedded passwords, ignore them or refuse the entire
  logon.

- Allowing embedded SECURITY passwords.


Allowing embedded SECURITY passwords``contents`news
Allowing embedded SECURITY passwords

  Even though this appears to be the exact opposite of the above feature, it is
  only usable for NETWORK originated logons (from products such as DSCOPY on
  HP-UX or ODBC on an IBM PC or compatible computer).  With the HELLO task
  active, you may now embed SECURITY passwords in your logon string using the
  same syntax as is used for MPE passwords.  Although we don't recommend this
  practice, it has been incorporated into our software to allow access from
  "foreign" systems (e.g., UNIX systems or PCs) to be better secured by
  allowing the user of the foreign system to specify their SECURITY password as
  well as their MPE password(s).

  UNIX/PC programs such as DSCOPY or ODBC don't give the user the opportunity
  to interactively log on to the HP3000.  Instead, these programs expect the
  user to supply a complete logon string with embedded passwords which they
  will then use to access the HP3000.  These programs obviously do not expect
  to see a "What is your mother's maiden name?" prompt once they have logged
  on, so they do not interact with our software.  By allowing the user to embed
  their SECURITY password using the same syntax as an MPE password (i.e.,
  JOHN/SECPASS,USER/UPASS.ACCT/APASS) our software will now correctly identify
  these users.

  Note that not all applications will work -- the application may not make a
  provision for the user to insert a "session" password.  This could be due to
  the fact that the application doesn't allocate a long enough string to
  accommodate the session password or perhaps the application prompts the user
  for each "known" field of a logon and builds the :HELLO command internally.

  This feature is discussed in greater detail in the following sections: -
    CONFIGURING HELLO TRAP FOR REMOTE ACCESS SECURITY -Checking embedded
    SECURITY passwords during logon

- Preventing non-SM users from disabling Procedure Exit traps


Disabling PEUTIL "disallow" command``contents`news
Disabling PEUTIL "disallow" command

  As procedure exits are currently implemented by HP, any user may use the
  program PEUTIL.PUB.SYS to disable Procedure Exit traps system-wide.  It is
  possible to close this loophole, and protect Procedure Exits from
  unauthorized deactivation.

  Refer to the description of the $PEUTIL keyword in the 'Configuring HELLO
  trap...' section for more information.

CONFIGURING HELLO TRAP FOR LOGON SECURITY


Configuring HELLO trap for LOGON security``contents`news
Configuring HELLO trap for LOGON security

The HELLO.DATA.VESOFT configuration file is used to define the actions
performed by HELLO trap.  It must be kept unnumbered.  The file may contain any
number of '$' prefixed keywords, which may be followed by one or more
parameters.  These parameters must be on the same line, and must be delimited
by one or more blanks.  The file may contain blank lines, and comments
delimited by pairs of (* and *).

The following keywords are available (others are documented in the section
"Configuring HELLO trap for Remote Access Security" later in this manual):


ASSUME-HELLO, HELLO trap keyword``contents`news
$ASSUME-HELLO, HELLO trap keyword

 $ASSUME-HELLO              Automatically inserts 'HELLO' at the start of the
                             user's logon command, if it is not already
                             present.

                             This command may be used in conjunction with
                             $HELLO definitions to allow users to logon by
                             simply entering their name, in effect allowing
                             UNIX-style logons on the HP3000.

                             It is important that this command be located after
                             any $CHANGE commands, and before all $HELLO
                             commands in the configuration file.


CHANGE, HELLO trap configuration keyword``contents`news
$CHANGE, HELLO trap configuration keyword

 $CHANGE <from> <to>        Changes 'from' string to 'to' string within logon
                             string.  Intended to allow synonyms for HELLO to
                             be defined.  The 'from' and 'to' strings may not
                             contain embedded spaces.

                             For example, if the following configuration
                             command is used:

                             $CHANGE  HI     HELLO

                             users may logon using 'HI' as well as 'HELLO'.

                             If the following configuration commands are used
                             (in the order shown):

                             $CHANGE  HELLO  BYE
                             $CHANGE  HI     HELLO

                             then users may only logon using 'HI'.  Any attempt
                             to specify 'HELLO' will have exactly the same
                             effect as typing 'BYE'.


HELLO, HELLO trap configuration keyword``contents`news
$HELLO, HELLO trap configuration keyword

 $HELLO <id> <equivalent>   Replaces 'id' string with the 'equivalent' logon
                             string.  Intended to allow abbreviated logons to
                             be defined.  Only takes effect for 'HELLO'
                             commands (or for HELLO synonyms defined using the
                             $CHANGE command).

                             The 'equivalent' logon string may contain ';'
                             delimited HELLO parameters, but may not contain
                             any embedded spaces.

                             For example, if the following configuration
                             command is used:

                             $HELLO DICK  RICHARD,MANAGER.SYS;HIPRI

                             then users may logon by typing 'HELLO DICK'.

                             It is possible (but NOT recommended) also to
                             specify the passwords associated with an
                             abbreviated logon.


NOPARM, HELLO trap configuration keyword``contents`news
$NOPARM, HELLO trap configuration keyword

 $NOPARM <value>            Strips PARM=<value> from all logon strings or
                             strips all negative values if <value> is not
                             specified.

                             This keyword may be specified more than once if
                             you wish to prevent use of multiple PARM values.


PEUTIL, HELLO trap configuration keyword``contents`news
$PEUTIL, HELLO trap configuration keyword

 $PEUTIL refuse | allow | allow-sm
                             Specifies whether access to the PEUTIL.PUB.SYS
                             program's "disallow" command is to be allowed.

                             One of the following keywords should be supplied
                             to indicate how attempts to disallow Procedure
                             Exits system-wide would be handled:

                               REFUSE   .. Blocks disallow unconditionally
                               ALLOW    .. Allows disallow unconditionally
                               ALLOW-SM .. Restricts use of disallow to
                                           SM-capability users

                             ALLOW-SM is enforced by default.

The entire HELLO.DATA.VESOFT file is parsed during every logon attempt, hence
we don't recommend that you add unnecessary entries to the file.

A default HELLO.DATA.VESOFT file will be installed automatically by the VESOFT
installation job (it does not contain entries that change the default behavior
of your system).

SEQUENCE OF ENTRIES WITHIN THE CONFIGURATION FILE

The HELLO.DATA.VESOFT configuration file controls not only the changes to the
logon string, but authorization for network originated logons using utilities
that normally bypass the LOGON UDC as well.  The following list shows the
proper order for all the keywords that may be specified in this file:

1)  Logging commands:

      $MPELOG
      $SECLOG
      $DEBUGLOG

2)  Hello synonym definitions:

      $CHANGE

3)  Assume-Hello definition:

      $ASSUME-HELLO

4)  Hello abbreviation definitions:

      $HELLO

5)  Configuration commands:

      $NOPARM
      $TIMEOUT
      $BACKUP
      $CONFIG
      $PEUTIL


Setting up special passwords: the $PASS keyword ``contents
Setting up special passwords: the $PASS keyword
$PASS, SECURCON file keyword for special passwords

The $PASS keyword (also described under "Terminal Passwords", later in this
manual)  allows you to assign special passwords to particular usersets.

The actual syntax of the $PASS keyword is:

   $PASS  "pass1[/(userset1)] [,pass2[/(userset2)]...]"
          "password type"
          userset

   * Each $PASS keyword will (potentially, depending on the userset) cause the
     user to be prompted for an additional password at logon time.

   * You can have multiple passwords, separated by commas.  All lower-case
     letters will be UPSHIFTED before the password is compared to what the user
     types in.

   * Each password can have it's own "usersetN", which means that only tho
     those users are permitted to use that password.

   * The "password type" can be anything you like; it is used as part of the
     prompt SECURITY issues at logon time, and in the SECURITY log file (see
     "SECURITY's Logging Facility", above).

   * The entire keyword can be restricted to a particular userset.

   * The usersets can be any VESOFT usersets, as documented in the "Usersets"
     section of this manual.  Of course, "userset1", "userset2", etc.  should
     be subsets of the final "userset" parameter; the $PASS will not apply to
     any users who are not included in the final "userset".

A few examples should give you an idea how powerful and flexible this feature
is:

   $PASS "WHOPPER"      "SM/PM PASSWORD"  CAP=SM CAP=PM
   $PASS "MTFBWY"      "OP PASSWORD"     CAP=OP
      (* extra password for users with special capabilities *)

   $PASS "WORKLATE"  "OFFHOURS PASSWORD"
         DAY=1 DAY=7 TIME<8:00 TIME>18:00
      (* special password during off hours *)

   $PASS "OPERONLY"  "CONSOLE PASSWORD"  LDEV=20
   $PASS "THX1138" "MODEM PASSWORD"  @.DEVELOP&LDEV=MODEM
   $PASS "WALDO"   "MODEM PASSWORD"  LDEV=MODEM-@.DEVELOP
   $PASS "HAMMER"  "MODEM PASSWORD"  HPDTCPORTID="0800090045b5 0100 "
      (* also see "Terminal Passwords", later in this manual *)

USER-DEFINED FIELDS IN SECURITY USER PROFILES


User-defined fields in SECURITY user profiles ``contents
User-defined fields in SECURITY user profiles


USER-FIELD, SECURCON file keyword ``user`field
$USER-FIELD, SECURCON file keyword
always keeps certain information associated with each user profile --
the user's real name, terminal, day-of-week, and time-of-day restrictions, the
applicable menu file, etc.  This information is entered into the database when
the user is added, is changeable using the CHANGE option, listable using
LISTUSER (which also lets you select on it), and, most importantly, may be used
by SECURITY at logon time to check if the user is to be allowed to log on.

What if you want to define your own such fields? For instance, you may want to
keep in each user's profile the user's department -- and have the ability to
add it, change it, select on it, and even use it to control logons (e.g.
forbid access to users in this department whenever a particular job is
running)?

SECURITY user-defined fields facility lets you do this.  Just add to your
SECURCON file the line

   $USER-FIELD DEPT "Department name: "

This tells SECURITY about a user-defined field named DEPT which is to be
prompted for (at ADD/CHANGE time) with the string "Department name:".  Once
you've done this,

   * Whenever you add a user using the ADD entry point, you will be prompted
     for the department name.

   * Whenever you change a user using the CHANGE entry point, the menu of
     options will include "DEPT: Department name:".  You can change the user's
     department name by typing DEPT when prompted for the item to be changed.

   * Whenever you add/change a user using the SEC commands, you will be allowed
     to specify ;DEPT=xxx to set the department name to the given value, e.g.

        %SEC ADD JOE,CLERK.PROD;MENU=PRODMENU.DATA.PROD;DEPT=AP

   * In the %SEC commands, you will be able to select users by their DEPT field
     value using the function UF('DEPT'), e.g.

        %SEC OBSVEPASS @.PROD(UF('DEPT')='AP')

     (which will obsolete the SECURITY passwords of all profiles whose DEPT
     field is set to 'AP').  You will also be able to use UF('DEPT') in the
     LISTUSER selection conditions.

   * Most importantly, you will be able to control whether or not a user may
     log on using the $FORBID keyword in SECURCON.DATA.VESOFT and the UF('xxx')
     function.  Thus, for instance, you could say:

           $FORBID
             "UF('DEPT')='AP' and JSCOUNT('APSTORE,MGR.PROD')<>0"
             "APSTORE in progress, can't log on now"
             @.PROD

     which would forbid all users in the PROD account (@.PROD) whose DEPT field
     is 'AP' from logging on while there's a job called 'APSTORE,MGR.PROD'
     running.

This can be a very powerful and flexible tool.  For instance, say that you want
to be able to add temporary user profiles that automatically stop working on a
given day.  You can simply add the following lines to your SECURCON file:


Expiration of user profiles, $USER-FIELD example

   $USER-FIELD EXPDATE "Enter expiration date (MM/DD/YY): "
   $FORBID
     "VALIDDATE(UF('EXPDATE'),'MDY') &
        AND TODAY>DATEPARSE(UF('EXPDATE'),'MDY')"
     "Your user profile has expired"

The $FORBID expression says "if the expiration date is valid and today is after
the expiration date, forbid access"; you can also run (every night or every
week) a job that automatically cleans expired users out of the database using
the command:

   %SEC DELETE @.@(VALIDDATE(UF('EXPDATE'),'MDY')<>'' AND &
               TODAY>DATEPARSE(UF('EXPDATE'),'MDY'))


USER-FIELD-FORBID, SECURCON file keyword ``field`forbid
$USER-FIELD-FORBID, SECURCON file keyword
P, SECURCON expression variable for $USER-FIELD-FORBID
do you make sure, though, that the expiration date field always contains a
valid date? For this, you could use the $USER-FIELD-FORBID keyword:

   $USER-FIELD-FORBID EXPDATE "P<>'' and NOT VALIDDATE(P,'MDY')"
                      "Expected nothing or a valid MM/DD/YY date"

This is just like a $FORBID keyword in that it evaluates an expression (here
"P<>'' and NOT VALIDDATE(P,'MDY')"), and if it's true, prints the given error
message ("Expected nothing or ...") and rejects the input.  Note that the first
parameter here is EXPDATE, the name of the user field, and the value input by
the user is referred to in the expression by the special variable P.

Just as you can have more than one $FORBID, you can have more than one
$USER-FIELD-FORBID for the same field or for different fields; a value input
for the field is rejected if any of the $FORBID expressions are matched for
that field.

The $USER-FIELD-FORBID expression can refer to parts of the user profile (MENU,
HASVEPASS, etc.; for a complete list, see the "SECURITY User Profile Attribute
Variables" listed in the the "Listing User Profiles" chapter, above) which will
also work for other user-defined fields ("UF('xxx')") -- for instance,

   $USER-FIELD-FORBID FIELD2 "P=UF('FIELD1')"
                             "FIELD1 and FIELD2 same!"

will reject input to FIELD2 if it's the same as the value of FIELD1.  Note,
however, that since the user fields are prompted for in order, the
$USER-FIELD-FORBID expressions for a given field can only refer to preceding
user fields.

Finally, what if you only want a particular user field to apply to a particular
userset? The main reason for this would be if you don't want to burden yourself
at ADD time with prompts that might not really apply to this particular
profile.

By specifying a userset (or several usersets) after the prompt string parameter
of $USER-FIELD, e.g.

   $USER-FIELD DEPT "Enter department: " @.PROD @.REMOTE

you can restrict the DEPT user field to apply only to the PROD and REMOTE
accounts.  Similarly, by specifying a userset (or several) after the error
message string parameter of $USER-FIELD-FORBID, you can restrict that
particular prohibition to only those usersets.

Note: if you specify a userset on $USER-FIELD, you must limit any
$USER-FIELD-FORBIDs to the same userset (or a subset).  Setting a
$USER-FIELD-FORBID on a userset that does not have the same $USER-FIELD set for
them will cause an error.

CHANGING THE SECURITY WELCOME MESSAGE


Changing the SECURITY welcome message ``contents
Changing the SECURITY welcome message


WELCOME-MESSAGE, SECURCON file keyword ``welcome`message
$WELCOME-MESSAGE, SECURCON file keyword

$WELCOME-MESSAGE "text" [usersets]

EXAMPLE:
   $WELCOME-MESSAGE "Welcome to the ACME HP3000!" @.@
   $WELCOME-MESSAGE "Accounting backup: Thursday 7:00PM-9:00PM" @.ACCTING
   $WELCOME-MESSAGE "Please log off before that time!"          @.ACCTING

When a user logs on through SECURITY, we print a welcome message for him (which
defaults to "Welcome!  You are now logged on.").  You can use the
$WELCOME-MESSAGE keyword to change it if you'd like, e.g.  $WELCOME-MESSAGE
"Welcome to system XYZZY".  With the userset parameters, you can specify a
different welcome message for different users or accounts (something that you
can't do with MPE's :WELCOME message), e.g.

   $WELCOME-MESSAGE "Welcome to ACME's AP system." @.AP

If more than one $WELCOME-MESSAGE keyword applies to the user (i.e.  he is
included in the userset for more than one), all of the $WELCOME-MESSAGEs that
apply will be printed, one per line.  This gives you a way to have
multiple-line welcome messages.

To turn the welcome message off altogether, just say

$WELCOME-MESSAGE ""

AUTOMATICALLY EXECUTING COMMANDS AT LOGON TIME


Automatically executing commands at logon time ``contents
Automatically executing commands at logon time
Adding commands to be executed at logon time

Suppose you want to execute a set of commands whenever a particular user (or
set of users) logs on to the system? Maybe you want to issue some
:FILE-equations or run an email-checking program, or...

One way to do it (the only way, if you don't have SECURITY) would be to add an
OPTION LOGON UDC.  Normally, if the command to be executed is designed for all
users on the system, this is set at the SYSTEM level.  This has several
problems:

   * UDCs are difficult to change.

   * UDCs can only be set at the SYSTEM, ACCOUNT and USER level.  If you have a
     particular task that you only want done for certain users, in several
     accounts, you have to do a :SETCATALOG for each of those users (and how
     are you going to find out later who you set a particular UDC catalog
     for?).

   * There can be only one OPTION LOGON UDC at each "level", and as we
     recommend setting LOGONUDC.PUB.VESOFT first, this would preclude your
     ability to set an OPTION LOGON UDC of your own at the system level.


ACCOUNT/USER level OPTION LOGON UDCs & SECURITY menus

  * Because OPTION LOGON UDCs are executed in the order of SYSTEM, ACCOUNT,
     and then USER, users who have been configured to use a menu will NOT
     execute ACCOUNT or USER level UDCs! Users who are configured to use a menu
     REMAIN in the logon program until they exit the menu, at which point they
     are logged off.

   * Errors in OPTION LOGON UDCs can seriously affect you system security or
     (on the other hand) prevent you from logging on to your system again!

Of course, SECURITY provides a solution to these problems (and, as with most of
our solutions, adds additional capabilities previously undreamed-of)! Note: if
you are using SECURITY's logon menus, also see the discussion of "*START" in
"Logon Menus Revisited: A Detailed Explanation" in this manual.


LOGON-EXECUTE, SECURCON file keyword ``logon`execute
$LOGON-EXECUTE, SECURCON file keyword
a line of the form:

   $LOGON-EXECUTE "expression" userset1 userset2 ...

causes the given expression to be executed at logon time for the users in the
given userset.  The expression can be any of the ones described in the
Appendix, however,the most useful "expression" is a call to the MPE(...)
function.  For example, this $LOGON-EXECUTE expression sets a file equation for
a laser printer that all users might want to access:

   $LOGON-EXECUTE "MPE('FILE LASER;DEV=LJ')" @.@

Notice that the entire expression must be enclosed in quotes, and that some
functions, like the MPE(...) function shown here, also require string
parameters which are enclosed in quotes as well.  An alternate expression
function to use in some cases is the SVARSET function.  This function will let
you set the HPPATH variable for XL systems as follows:

  $LOGON-EXECUTE
     "SVARSET('HPPATH',HPGROUP+',PUB.'+HPACCOUNT+',PUB.SYS')" @.@

Finally, remember that you can use all of the User Profile Attribute Variables
defined in the "Listing User Profiles" section of this manual.  The following
example shows how to display the date, time, and terminal number of the last
successful logon for this user (this is required by some security standards).

  $LOGON-EXECUTE
     "IF LASTLOGONLDEV<>0 THEN &
        WRITELN ('Last logon: ', LASTLOGONDATE, ' ', &
             LASTLOGONTIME, ', on ', LASTLOGONLDEV)" @.AP @.PROD

$LOGON-EXECUTE and %CHLOGON/%CHGROUP


LOGON-EXECUTE and %CHLOGON/%CHGROUP``news
$LOGON-EXECUTE and %CHLOGON/%CHGROUP

The MPEX %CHLOGON (and %CHGROUP) commands will execute any $LOGON-EXECUTE
commands that are appropriate for the target logon.  Sometimes, this may not be
desired (such as running a program from a $LOGON-EXECUTE), but since a %CHLOGON
is virtually indistinguishable from a normal logon, how can you avoid executing
a command "sometimes"? Actually, the answer is quite simple -- we provide two
functions, ISCHGROUPED() and ISCHLOGONED(), that indicate if a user has just
changed from one group to another or from one logon ID to another.
ISCHLOGONED() is TRUE if the MPEX %CHGROUP or %CHLOGON commands were used,
ISCHGROUPED() is TRUE only if the %CHGROUP command was used.

In the $LOGON-EXECUTE, this can be used as follows:

  $LOGON-EXECUTE "IF NOT ISCHLOGONED() THEN MPE('run myprog')" @.@

In this $LOGON-EXECUTE, the function ISCHLOGONED() is tested, and if it returns
FALSE (i.e., this is a normal logon and not a %CHLOGON), the program MYPROG is
run using the MPE() function.

SECURITY VIOLATION HANDLING


SECURITY violation handling ``contents
SECURITY violation handling
$VIOLATION-EXECUTE, SECURCON file keyword
P, SECURCON expression variable for $VIOLATION-EXECUTE

$VIOLATION-EXECUTE "expression" userset1 userset2 ...

EXAMPLE:

  $VIOLATION-EXECUTE
     "MPE('TELL SECMGR.AP '+P+' on LDEV !HPLDEVLIST')" @.AP
  $VIOLATION-EXECUTE
     "SECURITYLOG(P+' on DTC port '+HPDTCPORTID)" @.@

Specifies an expression to be executed when a SECURITY violation takes place
for the given usersets.  The expression can be any of the ones described in the
Appendix, and all the SECURITY user profile attribute variables (see "SECURITY
User Profile Attribute Variables" in the Listing User Profiles chapter, above)
can be used inside it.  In addition, the special variable P is set to the text
of the violation message (e.g.  "BAD PASSWORD", "BAD TIME", etc.).

The first example given sends a message to the user SECMGR.AP whenever a
violation takes place for a user in the AP account.  The second example writes
a violation record to the SECURITY log file that contains the DTC port ID
(useful on large systems with "non-nailed" DTCs, which don't have fixed LDEV
numbers).  You might also, say, run your own program to do your own sort of
security logging or violation processing, output an additional message to the
user or do anything else you like.

FORBIDDING CONCURRENT SESSIONS WITH THE SAME LOGON IDs


Forbidding concurrent sessions with the same logon IDs ``contents
Forbidding concurrent sessions with the same logon IDs
$NO-CONCUR-SESS, SECURCON file keyword

One feature that many auditing standards require is an ability to prohibit the
same user from logging on to more than one terminal at a time.  This is often
quite reasonable, since such a concurrent logon -- one where a session with
exactly the same session name, user ID, and account name is already logged on
to the system -- usually means one of two things:

   * The user left one terminal unattended to go work on another terminal.
     This is not good because unattended terminals may be security threats
     (since anybody can walk up and use the terminal without having to log on
     and specify a password).

   * Two different people are logging on using exactly the same logon.  This is
     also not good because a logon (session name, user ID, and account name)
     should -- for audit trail purposes -- uniquely identify an individual; if
     two people are using the same logon, they must be sharing the same
     password, and the more people share a password the harder it is to keep
     the password secure.

SECURITY lets you forbid such concurrent logons by simply specifying in the
SECURCON.DATA.VESOFT file

   $NO-CONCUR-SESS [usersets]

e.g.

   $NO-CONCUR-SESS @.AP @.PROD CLERK.PAYROLL

In this example, whenever anybody logs on to the AP or PROD account or as the
user CLERK.PAYROLL, SECURITY makes sure that there is no other session logged
on at the time with exactly the same session name, user ID, and account name.

Thus, if JOE,CLERK.PAYROLL tries to log on, he will be refused access if
there's already a session for JOE,CLERK.PAYROLL; however, if there's a session
of JOHN,CLERK.PAYROLL or JOE,CLERK.AP, then JOE,CLERK.PAYROLL will be allowed
to log on.  Only exact matches -- exactly the same session name, user ID, and
account name -- are forbidden.  (If you want to be more general in the matches
that you want to forbid, see the discussion on the $FORBID keyword and the
JSCOUNT function.)

:ALLOWing CONSOLE COMMANDS BY USER ID


:ALLOWing console commands by user ID ``contents
:ALLOWing console commands by user ID
$ALLOW, SECURCON file keyword

Standard MPE permits you to :ALLOW console commands (like :REPLY,
:DELETESPOOLFILE, :ABORTIO, etc.) either to:

   * everybody -- all users in the system,

   * or, to an individual session (but only until the session dies).

It's impossible to grant :ALLOWs in the same way you grant capabilities --
"always :ALLOW the user JACK.DEV the commands :REPLY, :ABORTIO, and
:ALTSPOOLFILE".  The :ALLOW-to-individual-session feature is rarely used since
when the session dies, the :ALLOWs die with it -- whenever the person logs on
again, he has to get the operator to do the :ALLOW again.

SECURITY lets you :ALLOW commands to arbitrary usersets.  For instance, you
might specify in the SECURCON file:

   $ALLOW REPLY,ABORTIO,ALTSPOOLFILE JACK.DEV
   $ALLOW RESUMESPOOL,SUSPENDSPOOL @.AP PETE,@.@
   $ALLOW @ CAP=SM

The above commands will:

   * let any session logged on as JACK.DEV use the :REPLY, :ABORTIO, and
     :ALTSPOOLFILE commands;

   * let anybody in the AP account and anybody logged on with session name PETE
     use the :RESUMESPOOL and :SUSPENDSPOOL commands;

   * let anybody who logs on to a user with SM capability use any console
     command.

The last line -- "$ALLOW @ CAP=SM" -- is particularly useful.  With it, you can
make sure that any SM user you have (who can always switch the console to his
terminal anyway) will automatically be allowed to use all the console commands,
even if he doesn't log on to the console.  Personally, I think that's the way
MPE should have worked all along.

IMPOSING SYSTEM-WIDE SESSION NAME STANDARDS


Imposing system-wide session name standards ``contents
Imposing system-wide session name standards
$SESS-EDIT, SECURCON file keyword

As we mentioned earlier, SECURITY can let you impose passwords on a session
name basis, providing security for sites which use session names -- rather than
user IDs -- to distinguish one user from another.

However, under some circumstances you might be using session names, but not for
security purposes:

   * You may not really need security for some accounts (e.g.  the development
     account) but still want to have people log on with a session name
     indicating who they are (so :SHOWJOBs are more informative).

   * You may be distinguishing users by the MPE user ID, but like to have
     people log on with a job/session name that indicates their phone system
     extensions (so the console operator can easily call them if something
     happens).

   * You may also have cost accounting systems driven off the session names
     recorded in system log file records.

In these cases, you don't so much want to restrict people to a certain
well-defined set of session names (which is what the session name security
feature lets you do) as just enforce certain standards for session names.  The
most common desire is to require some sort of session name (really anything at
all), just to prevent lazy or forgetful users from omitting the session name
altogether.

To do this, you may simply specify in your SECURCON.DATA.VESOFT file

   $SESS-EDIT "?@"

The session name edit mask -- "?@" -- is very much like the standard MPE
wildcard pattern, where a "?" means "exactly one character" and "@" means "zero
or more characters".  The "?@" pattern therefore means that the session name
must have one or more character (i.e.  must be specified).

Other patterns may, of course, be indicated as well:

   $SESS-EDIT "???@"

means the session name must be three or more characters long;

   $SESS-EDIT "X####"

means the session name must be X followed by four digits (perhaps the user's
telephone extension); one of our users' cost accounting system requires the
pattern

   $SESS-EDIT "??#???"

indicating exactly six characters, the third of which is a digit (some sort of
cost allocation code).  You have complete flexibility to organize your
standards any way you like.

Of course -- like all SECURCON.DATA.VESOFT keywords -- $SESS-EDIT can be
qualified to indicate exactly to whom you want the standards applied.  For
instance, you might very well say:

   $SESS-EDIT "???@" @.@-OPERATOR.SYS

to prevent OPERATOR.SYS (who is normally logged on without a session name) from
having to satisfy the session name restrictions.  Similarly, a very useful
option is

   $SESS-EDIT "X####" ONLINE

which simply means that the session name edit mask will apply only to sessions,
not to jobs (which would also normally have the same restriction).  You might
very well have a number of job streams with some sort of self-describing
job/session name -- you wouldn't want them to be restricted in the same way.
In fact, it's a good bet that you'd almost always want to restrict the
$SESS-EDIT checks to online only, although you might specify something like:

   $SESS-EDIT "X####" ONLINE&@.DEV
   $SESS-EDIT "?@" BATCH-@.TELESUP

which means that:

   * DEV account sessions must have a session name of X followed by four
     digits;

   * all jobs except TELESUP account jobs must have some job name;

   * all other jobs and sessions may or may not have any session name they
     please.

SHOWING USER PARAMETERS AND APPLICABLE OPTIONS


Showing user parameters and applicable options ``contents
Showing user parameters and applicable options
SHOW, MAIN.PUB.VESOFT entry point
Trouble-shooting

An end-user calls you up and says "Help!  The system won't let me log on!" What
do you do?

Well, there are a number of possible reasons why SECURITY may forbid a user
from logging on.  His terminal/time-of-day/day-of-week access restrictions may
be in force; his logon may be obsolete; his user may have been deactivated due
to too many invalid logon attempts.  Usually, the reason should be quite clear
from the SECURITY error message.

Sometimes, though, things may be a bit difficult to understand; for instance,
you might not realize that the user's logon matches one of the usersets
specified in the SECURCON.DATA.VESOFT options; or, you might not be aware that
the user inherits his SECURITY passwords from some other user profile.  With
the many options and features that SECURITY has, you need a simple way to find
out which are applicable in a particular situation.

What you can do is this:

   :RUN MAIN.PUB.VESOFT,SHOW

   SECURITY/SHOW 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter user ID: TEST
   Enter account: VESOFT
   Enter session name: SASHA
   LDEV from which logon will take place: 22
   Show (A)ll parameters or only the (N)on-default values? N

What you've done is asked SECURITY:

   "If a user logs on as SASHA,TEST.VESOFT on LDEV 22, what will SECURITY think
    about him?"

MAIN.PUB.VESOFT,SHOW will show something like the following:

   $VEPROFILE          SECURITY user profiles are ENFORCED
                         User is SASHA,TEST.VESOFT
                         Real name is SASHA VOLOKH
                         Access allowed on all days,  7 AM - 8 PM
   $VE-DIFF-PASS       User may not have two or more identical
                         SECURITY passwords

   $MPE-OBSOL          MPE password obsolescence is enforced
   $MPE-OBS-DAYS       Passwords expire after 30 days
   $MPE-PASS-EDIT      MPE password must match the pattern ?@

   $TERM-DEACTIVATE    Terminal will be :DOWNed after 3
                         consecutive invalid logon attempts

   $NO-CONCUR-SESS     Concurrent sessions with same session name,
                         user ID, and account name are FORBIDDEN

As you see, all the SECURITY options (except those that are set to their
default values) that pertain to this user are shown.  In particular, you see
his user profile information, his MPE password obsolescence flags, and so on.
If you wanted to see all the option settings (including those that are at their
default values), you could have just replied "A" when asked for (A)ll or
(N)on-default values.

ALLOWING A USER TO LOCK UP HIS TERMINAL BEFORE LEAVING IT UNATTENDED


Allowing a user to lock up his terminal before leaving it ``contents
Allowing a user to lock up his terminal before leaving it
:LOCKUP, UDC used to lock up a terminal
LOCKUP, MAIN.PUB.VESOFT entry point
Unattended terminals: avoiding with LOCKUP

A major threat to user security is a user leaving his terminal unattended.
Anybody can then walk up to the user's terminal and use the computer without
having to go through any logon security check.  What's more, any audit trails
you may have will be compromised -- all the violator's activity will be logged
under the user ID of the user whose terminal he's using.

Of course, SECURITY includes the LOGOFF module (described later on in this
manual) which can :ABORTJOB all users whose terminals are idle more than a
certain length of time (indicating that the terminal may very well have been
left unattended).

This is very good as far as it goes, but has a few problems.  For one, if you
set the LOGOFF timeout to, say, 15 minutes, and a user walks away from his
terminal, LOGOFF won't abort him until 15 minutes later -- this is better than
not logging him off at all, but still in those 15 minutes some security
violator can come up to the terminal and use it.

Also, if a user wants to leave but intends to come back, he may not want to log
off (since it'll take extra time and effort to log back on later).

If you're concerned about this, you can use SECURITY's :LOCKUP feature.  Simply
put, a user can always type in

   :LOCKUP

(a UDC defined in the LOGONUDC.PUB.VESOFT file -- the same file that defines
the SECURITY OPTION LOGON UDC).

MPEX users note: you can only use the ":LOCKUP" UDC from within MPE; do NOT use
it within MPEX -- it will NOT secure your terminal if you do so.

At that point, SECURITY will prompt him for his MPE passwords, his terminal
password, and for his SECURITY password, just as it would at logon time.  If an
unauthorized user walks up to the unattended terminal, he'll be confronted with
these questions, and if he can't answer them, the session will be logged off.

On the other hand, if the original user comes back, he'll know the passwords
being asked for, and when he types them in correctly, he'll be put back into
his normal session, ready to go on with whatever he was doing before.


LOCKUP-MPE-PASS, SECURCON file keyword ``MPE`password
$LOCKUP-MPE-PASS, SECURCON file keyword
you'd like, you can prevent LOCKUP from re-prompting for a user's MPE
passwords (while still having it prompt for the SECURITY and terminal
passwords, if any) using the $LOCKUP-MPE-PASS keyword of the
SECURCON.DATA.VESOFT file.  For instance, if your SECURCON file says:

   $LOCKUP-MPE-PASS @.AP

then only AP account users will be re-prompted by LOCKUP for their MPE
passwords as well as their SECURITY and terminal passwords; other users will be
re-prompted only for their SECURITY and terminal passwords.

Saying

   $LOCKUP-MPE-PASS OFF

will turn off MPE password prompting for all users.

If you use SECURITY logon menus (which we highly recommend -- see "Logon
Menus", "Logon Menus Revisited: A Detailed Explanation", and "Logon Menus:
Advanced Features" in the Logon Security section of this manual) you may also
be interested in the $MENU-LOGOFF-LOCKUP facility described in "Configuring
LOGOFF: Locking Up Sessions That Use SECURITY Menus (Instead Of Aborting Them)"
in Unattended Terminal Security.

WHAT IF THE SECURCON.DATA.VESOFT FILE CAN'T BE ACCESSED?


What if the SECURCON.DATA.VESOFT file can't be accessed? ``contents
What if the SECURCON.DATA.VESOFT file can't be accessed?

The SECURCON.DATA.VESOFT file defines virtually all of the security
restrictions that SECURITY imposes.  It is only through the various SECURCON
keywords that SECURITY knows to prompt for SECURITY user passwords, prompt for
terminal passwords, check for obsolete passwords, etc.

What if we can't access SECURCON.DATA.VESOFT? Or, what if it contains an error?
Perhaps it doesn't exist or is opened exclusively (usually inadvertently) or
has somehow been corrupted by a disc I/O error.

The concern here is not that it was intentionally deleted or modified by
somebody who wants to break into the system, since only the system manager and
MANAGER.VESOFT should have access to this file.  Rather, what if somehow,
through system manager error or computer error, the file has become
inaccessible or contains syntax errors.

Normally, if SECURITY can't access the SECURCON file, or if LOGON detects a
syntax error in the SECURCON file, it will allow anybody to log on.  This is
because we don't want an inadvertent system error -- e.g.  some sort of disc
I/O error that corrupts the SECURCON file's file label -- or a typographical
error made by the system manager to lock you out of your system.  Since
SECURCON can only be made inaccessible or have syntax errors, by accident (not
by an intentional security violator), we feel that it's better to risk a
temporarily insecure system than a total lock-out.


SECURITYMUSTHAVESECURCON, JCW ``SECURCON`must`have
SECURITYMUSTHAVESECURCON, JCW
, we realize that you may feel differently.  If you want SECURITY to
prohibit logons when the SECURCON file is inaccessible or contains syntax
errors -- and thus risk total lock-out if the file somehow gets damaged -- you
should insert a line saying

   SETJCW SECURITYMUSTHAVESECURCON = 1

into your OPTION LOGON UDC that runs SECURITY.


SECURITYANSWER, internal JCW used by SECURITY logon UDC
you want even more security (and more lock-out risk!), you can change the
"SETJCW SECURITYANSWER = 0" to "SETJCW SECURITYANSWER = 1", i.e.

   VESOFTSECURITY
   OPTION LOGON, NOBREAK
   SETJCW SECURITYANSWER = 1
   SETJCW SECURITYMUSTHAVESECURCON = 1
   CONTINUE
   RUN MAIN.PUB.VESOFT,LOGON
   IF SECURITYANSWER = 1 or CIERROR = 989 THEN
     CONTINUE
     BYE
     EOJ
   ENDIF
   ***

This makes sure that even if the MAIN.PUB.VESOFT program is inaccessible (e.g.
it's been accidentally destroyed or damaged), nobody will be allowed to log on.

Finally, we offer you a third alternative -- instead of saying

   SETJCW SECURITYANSWER = 1
   SETJCW SECURITYMUSTHAVESECURCON = 1

in your logon UDC, you can say

   SETJCW SECURITYANSWER = 1
   SETJCW SECURITYMUSTHAVESECURCON = 2

If SECURITYMUSTHAVESECURCON is set to 2 and the SECURCON.DATA.VESOFT file can't
be accessed at logon time (or it contains a syntax error), the user will be
logged off unless he's logging on to the system console.  This way, you can
have near-maximum security and lockout avoidance (since the console can be used
to log on even if SECURCON can't be accessed).

Of course, even if you set SECURITYMUSTHAVESECURCON to 2, all console logons
will still go through SECURITY -- it's only if the SECURCON.DATA.VESOFT file
can't be accessed that we'll let a console logon through.

It's all up to you -- you can:

   * increase security by setting SECURITYANSWER = 1 and
     SECURITYMUSTHAVESECURCON = 1,

   * increase safety by leaving SECURITYANSWER = 0 and not setting
     SECURITYMUSTHAVESECURCON at all,

   * or do something in between by setting SECURITYANSWER = 1 and
     SECURITYMUSTHAVESECURCON = 2.

Note, however, that even if you do get locked out, you will still be able to
avoid lockouts using the method described in the Avoiding Lockouts chapter of
this manual; however, this will require both a system re-boot and knowledge of
a "magic trick" described in more detail in that chapter.

AVOIDING LOCKOUTS


Avoiding lockouts ``contents
Avoiding lockouts


SUPER-PROTECT, SECURCON file keyword
$SUPER-PROTECT, SECURCON file keyword
job of SECURITY is to avoid unauthorized system access.  It does this by
enforcing the restrictions that you specified in the SECURCON.DATA.VESOFT file
and the SECURITY user profiles.

It is conceivable that because of system manager error, the configuration
options specified by SECURITY will altogether prohibit all logons.  For
instance, the system manager might add to the SECURCON.DATA.VESOFT file the
line

   $VEPROFILE @.@

(which indicates that "all users that try to log on must have SECURITY profiles
previously added using RUN MAIN.PUB.VESOFT,ADD" -- in and of itself a pretty
good idea) and then forget to add any SECURITY user profiles.

SECURITY, like all computer programs, does exactly what you tell it to do.  At
logon time, it sees that you want to deny access to all users that lack
SECURITY user profiles.  For every logon, therefore, it checks to see if there
is a user profile -- and, since no user profiles have been added, it rejects
every logon.  No new sessions will be able to log on.  If you reboot the
system, then you will have complete lock-out -- nobody will be allowed to log
on at all.

You see our dilemma -- on the one hand, our job is to deny access to what is
defined by the system manager as "unauthorized users"; on the other hand, the
system manager could easily make an honest mistake and deny access to "too
many" people.  Actually, he doesn't even need SECURITY to do this -- if he
accidentally set up a system-wide UDC such as:

   B
   OPTION LOGON, NOBREAK
   BYE

(say that he intended to make it OPTION LIST but, by accident, made it OPTION
LOGON instead), he'd get exactly the same result -- the system will do
precisely what he asked for, and log off every session that tries to log on.

Actually, we have one safeguard against the specific problem we mentioned -- if
we find that there are no SECURITY user profiles in existence, we won't enforce
the $VEPROFILE restriction.  Still, it's possible that there is one user
profile, but it's for the wrong user or has some access restrictions that make
it impossible to use or whatever.  As we mentioned, we have to enforce the
security restrictions that the system manager imposes; however, we don't want
to force a reload if the system manager makes a mistake.

There are two reasons we're saying all this:

* First, we want to warn you to be careful with setting up the configuration
  file -- make sure that the restrictions are exactly what you want them to be.

  One way to check is to make your changes to a copy of the SECURCON file, then
  use the command

     %SEC SHOW @.@; SECURCON=yourfile

  This will show you any syntax errors you've made in the SECURCON file.

  Another way is to simply

     :XEQ MAIN.PUB.VESOFT SECLOGON

  This will do everything that SECURITY does when you actually log on, but will
  not log you off if there is a problem.

* The second reason is that if you make such a mistake, there is a way to
  recover from it.

If you should accidentally lock yourself out of the system and there are no
sessions from which you can unlock things (any session with SM capability or
access to the GOD program can just do a :SETCATALOG to reset the SECURITY logon
UDC), then you can restart the system in a certain special way that will cause
SECURITY to temporarily waive all its security checking.  This can only be done
by somebody who has access to the system console and is able to reboot the
system, so it's not a security threat, and it is a useful fail-safe that allows
you to easily recover from lockouts.

If you want to know how to do this "just in case", have your system manager
write/FAX us at VESOFT.

Alternatively, you may place into your SECURCON.DATA.VESOFT file the line:

   $SUPER-PROTECT ON

which will disable this emergency algorithm altogether, thus giving you maximum
security (even against people who have access to the system console); however,
once you do this, the only way of recovering from system lock-outs is to do a
reload or use one of HP's stand-alone disc utility tools (such as SADUTIL).

To summarize:

   * SECURITY does exactly what you tell it to do.

   * It is possible for a system manager to accidentally cause a system
     lock-out by specifying excessive security restrictions without having a
     logged-on SM session that can reset system security.

   * If you do such a thing, there is a special emergency workaround that you
     can use if you're willing to reboot the system and if you have access to
     the system console, and if you know the MPE passwords to an SM user logon.

   * To find out the exact details of this workaround, you can write to us and
     we will inform you of it.

   * If you want to disable this emergency workaround altogether, you can do so
     by adding a "$SUPER-PROTECT ON" line to the SECURCON.DATA.VESOFT file.

   * Remember, system lock-outs will only happen if you make a mistake (and not
     just any mistake) in configuring SECURITY that makes it impose too much
     security.  Also, if you do find that you made such a mistake and you're
     still logged on as a user with SM capability, you can easily get rid of
     the problem by modifying the SECURCON.DATA.VESOFT file or at least
     resetting the system-wide SECURITY UDC.

CHECKING SECURITY PROFILES FROM WITHIN YOUR PROGRAM


VECHECKLOGON, to check SECURITY PROFILES within your program``contents
VECHECKLOGON, to check SECURITY PROFILES within your program

When a user logs on to the system, SECURITY performs various checks -- is his
password correct, is he allowed to log on to this terminal, has his password
expired, etc.  -- and, depending on the results, lets the user on or logs him
off.

Sometimes you may want these checks to be done not just at logon time, but from
within your own program.  For instance, you may want to:

   * Re-prompt the user for a password every time he enters a particularly
     sensitive module (in case the authorized user has walked away from his
     terminal and someone else is using it now).

   * Instead of having SECURITY prompt the user based on his logon ID, have
     your own program tell SECURITY to use a user profile based on, say, your
     system's own internal user names.

   * Have the user's password be prompted for in a V/3000 screen (or in some
     other way that is most convenient to your users), rather than have
     SECURITY prompt for the password itself.

To let you do this, we've created a special procedure called VECHECKLOGON which
does most of the checking that SECURITY does at logon time, but

   * Lets you specify for which user (session name, user ID, account, and
     group) the checking is to be done.

   * Lets you specify the passwords (rather than prompting for them itself).

   * Returns to you a status indicating whether or not all the checks have been
     passed (i.e.  the user is authorized to use the system), rather than
     printing this information to the terminal and logging off.

   * Returns to you other status information, such as whether the user's
     passwords are about to expire, rather than printing this information to
     the terminal.

This procedure is easily callable from COBOL 74 or 85, FORTRAN, PASCAL, C, and
SPL.

VECHECKLOGON's calling sequence is:

   VECHECKLOGON (mode, workbuff, inbuff, outbuff)

where:

   * MODE is a 16-bit integer by value.  Must be 1.

   * WORKBUFF is an array of 128 16-bit words.  Before you first call
     VECHECKLOGON, you should initialize this array to be all zeroes.  Do not
     modify this array after the first call; on all subsequent calls, pass this
     same array to VECHECKLOGON.

   * INBUFF is an array of 128 16-bit words.  Its layout is as follows:

     words       type   description
       0-  7     ca     Session name.
       8- 15     ca     User ID.  If blank, then the session, user, account,
                    and group will be set to the logon session, user, account,
                    and group.
      16- 23     ca     Account.
      24- 31     ca     Group.
      32- 38            Reserved.  Set to binary zeros.
      39- 42     ca     Terminal password.
      43         i16    Number of the password to check (if you have multiple
                    SECURITY passwords).  Use the record number in the
                    $VEPASS-PROMPT-FILE file, starting from 0.
      44- 83     ca     SECURITY password.
      84-127            Reserved.  Set to binary zeros.
     (Type "ca" means a character array, padded with blanks on the right up to
     the maximum length specified.)

     This lets you specify for which user SECURITY will do its logon checking,
     but if you set the user ID field to be all blanks or all binary zeroes,
     SECURITY will use the logon user information.  Other than the fields
     indicated above, the rest of the array must be set to binary zeroes.  We
     recommend that you initialize the array to binary zeroes first and then
     fill in the fields that you want.

     Note that you may set the terminal password or SECURITY password to blanks
     if you think that they won't be needed for this logon.  If they will be
     needed and you left them set to blanks, VECHECKLOGON will merely return a
     "BAD TERMINAL PASSWORD" or "BAD PASSWORD" error.

   * OUTBUFF is an array of 384 16-bit words.  Its layout is as follows:

     words       type   description
       0- 14     ca     Result of the check.  This may be one of:
                        "" (empty string) -- All checks passed.
                        "BAD DAY" -- Logon not allowed on this day of the week.
                        "BAD PASSWORD" -- Bad SECURITY password.
                        "BAD SESSION NAME" -- Session name doesn't match
                    $SESS-EDIT.
                        "BAD TERMINAL" -- Logon not allowed on this terminal.
                        "BAD TERMINAL PASSWORD" -- Bad terminal password.
                        "BAD TIME" -- Logon not allowed this time of day.
                        "BAD USER" -- No SECURITY user profile for this user.
                        "CAN'T ACCESS SECURCON FILE" -- SECURCON file is
                    inaccessible and SECURITYMUSTHAVESECURCON JCW is set.
                        "DEACTIVATED USER" -- User has been deactivated through
                    a $USER-DEACTIVATE (or through a %SEC DEACTIVATE command).
                        "EXPIRED xxx PASSWORD" -- User, account, group or
                    SECURITY password has expired (xxx indicates which it is);
                    for user and SECURITY passwords, this message is only
                    returned if the password has expired and the appropriate
                    $xxx-OBS-CHG keyword is not set (indicating that, even
                    though the password is expired, the user should be allowed
                    to log on if he changes the password).
                        "NO PASSWORDS YET" -- User was configured to be asked
                    for his SECURITY passwords when he first logs on, and he
                    hasn't logged on since then.
                        "SECONDARY LOGON ATTEMPTED" -- $NO-CONCUR-SESS is set
                    and another session with this session name, user ID, and
                    account is already logged on.
                        "USER HAS NO MPE PASSWORD" -- $MPE-U-NEED-PASS is set
                    and this user has no MPE password.
                        Anything else -- if any other value is returned, it is
                    the first 30 characters of one of your $FORBID error
                    messages (as specified in SECURCON).
      15- 39            Reserved.
      40         i16    -1 indicates that the user password has expired but
                    $MPE-OBS-PASSCHG is set; a positive integer indicates that
                    the user password expiration warning period has started,
                    and there are that many days left until the password
                    expires.
      41         i16    Same as word 40, but for account passwords.
      42         i16    Same as word 40, but for group passwords.
      43         i16    Same as word 40, but for SECURITY passwords.
      44- 58     ca30   The user's real name, as indicated in the database; if
                    no user profile exists for this user, 30 blanks.
      59-383            Reserved.


VEPROC.JOB.VESOFT, installing VECHECKLOGON
MPE/V and MPE/iX differences: calling VECHECKLOGON
order for VECHECKLOGON to be callable by anyone in the system, you can
stream the job VEPROC.JOB.VESOFT to put it into the system SL (you'll have to
re-stream it every time you get a new version of MPE).  This doesn't modify MPE
in any way, nor will it cost you anything in the way of system resources; it'll
just make VECHECKLOGON available to any program in the system that needs to use
it.

Note: this job also adds the VECMMND, VEOPEN and MPEXHOOK procedures to
SL.PUB.SYS.  See "What If Your Program Does A :STREAM Using The COMMAND
INTRINSIC?" in Batch Security and Job Stream Programming and "Installing
VEOPEN" in Database Security in this manual, and "MPEX HOOK" in the chapter on
Running MPEX of the MPEX User Manual for more details.

To call VECHECKLOGON from MPE/iX Native Mode programs, simply run the Native
Mode program with ;XL="VEPROCNL.PUB.VESOFT".  (You still need to stream the
VEPROC.JOB.VESOFT job mentioned above.) Or, you can re-:LINK your program with
the same ;XL="VEPROCNL.PUB.VESOFT" option.

SPEEDING UP LOGONS


Speeding up logons ``faster`contents
Speeding up logons

SECURITY has to do a lot of things when you log on; naturally, this takes some
time.  We don't think it takes too long a time (especially since logons
shouldn't be a very frequent thing), and we feel that the security benefits
that all this logon checking gives you more than justify the slight overhead.

However, if you are really concerned about logon time, there are several things
you can do to speed things up:

   * First of all, one of the major delays at logon time happens when MPE
     initializes its UDC catalogs (before SECURITY even starts up).  The time
     this takes is proportional to the number of UDC files you have (the more
     files, the more FOPENs) and to the size of each UDC file (the larger the
     file, the more FREADs).

     To speed up UDC initialization, we recommend that you minimize the number
     of UDC files you have set for each user and (on MPE/V systems) increase
     the blocking factor of each of those files.  The higher the blocking
     factor, the fewer disc I/Os will be needed for MPE to read the file.

   * Oddly enough, SECURITY's logon module spends most of its time not doing
     CPU processing or even reading files, but rather opening files.  The FOPEN
     intrinsic is quite time-consuming, and it pays to minimize calls to it.

   * If you have only one SECURITY password, you can specify its prompt
     directly in your SECURCON file using the $VEPASS-PROMPT keyword:

         $VEPASS-PROMPT "ENTER SECURITY PASSWORD: "

     Normally, SECURITY would have to read the VEPROMPT.DATA.VESOFT file to
     determine the password prompt; if you specify the prompt with
     $VEPASS-PROMPT, this file won't have to be accessed.

     Any $PASS-EDIT keywords (see the chapter on Enforcing SECURITY Password
     Standards) can also be specified inside the $VEPASS-PROMPT parameter
     string, e.g.

         $VEPASS-PROMPT "$PASS-EDIT '????@' ENTER PASSWORD: "

     (Note that the edit mask -- '????@' -- was enclosed in single quotes
     because the entire $VEPASS-PROMPT parameter was enclosed in double
     quotes.)

   * Whenever a user successfully logs on, SECURITY writes a log record into
     its log file.  If you don't want this to be done -- or you only want it to
     be done for some users -- you can use the $LOG-LOGON to restrict logon
     logging:

         $LOG-LOGON OFF   (* turn it off completely *)
         $LOG-LOGON @.AP @.GL   (* only on for some accounts *)
         $LOG-LOGON CAP=SM CAP=PM CAP=AM LDEV=60 LDEV=61 LDEV=63
                    (* only on for sensitive users or LDEVs *)

     If $LOG-LOGON is turned off for a user, SECURITY will be able to avoid
     opening, writing to, and closing yet another file.

     Note that even if you turn $LOG-LOGON off completely, all "attempted
     violation" log records -- written when a user enters a bad password or is
     for some reason forbidden to log on -- are still logged to the file.  We
     want to make things go faster for legitimate users, but we see no reason
     to be so nice to would-be violators.

   * If you use SECURITY logon menus, you can get rid of a good deal of
     overhead by simply saying

         $MENU-UDC OFF

     in your SECURCON.DATA.VESOFT file.  This tells SECURITY that none of the
     commands in the logon menus are UDCs, and thus saves the overhead of
     having to open and read all of a user's UDC files.  Needless to say, this
     will only work for you if your menus indeed do not use any UDCs.


MPE/V and MPE/iX differences: ALLOCATE

  * On MPE/V, you should either :ALLOCATE MAIN.PUB.VESOFT or turn on the
     AUTOALLOCATE feature of the operating system.  This eliminates a
     substantial amount of the work the loader must do whenever you :RUN a
     program.  On MPE/iX, the programs are in native mode and cannot be
     allocated.

The above suggestions should let you substantially speed up your logons.  There
will always be some additional overhead caused by SECURITY at logon time;
however, that's the price you have to pay (and we think that it's a rather
modest one) for security.

RESTRICTING ACCESS TO GOD.PUB.VESOFT


Restricting access to GOD.PUB.VESOFT ``contents
Restricting access to GOD.PUB.VESOFT

Say that you are the system manager and have to log on as a normal user to do
some trouble-shooting; or, you need to log on under a particular user ID to run
one of your programs.

Whenever you log on as a non-SM user, many of the things that you are used to
doing as SM no longer work.  You can no longer access the files that you need
to or run the programs that you need to; you can no longer :RUN some programs
with the ;DEBUG parameter.

The operating system looks at your logon ID, sees that this user doesn't have
SM capability, and forbids you any SM-level operation.  What MPE doesn't
realize is that you (personally) really are the system manager -- you just had
to log on as a user who doesn't have SM capability.

VESOFT's MPEX product includes a program called GOD.PUB.VESOFT (which you
should, of course, keep under a lockword) that temporarily grants you all the
capabilities and all the :ALLOWs on the system.  This way, if the system
manager has to log on as a "plain vanilla" user, he can run GOD and be the
system manager again, regardless of his logon.  (The user ID's capabilities are
not permanently changed -- when you next log on as this user ID, it'll have the
same capabilities that it did before; the system manager can also run a program
called MORTAL.PUB.VESOFT to return to his pre-GOD state without having to log
off.)

Since GOD has a lockword (whenever we install GOD on a system that didn't have
it before, we actually assign it a random lockword!), only the person who knows
the lockword (which should only be the system manager) can run it.

GOD can also be useful if some job stream that you have needs to acquire some
special capability or :ALLOW -- you can have it do a !RUN GOD.PUB.VESOFT,
perform the operation that needs the capability or :ALLOW, and then !RUN
MORTAL.PUB.VESOFT.  Using STREAMX's $NOPASS keyword, you can even do this
without having to embed the GOD lockword into the job stream.

GOD is not just a great convenience for the system manager; it can actually
enhance your system security.  If you don't use GOD, then you will inevitably
have more :RELEASEd files, weaker group and account security, and more global
:ALLOWs than necessary.  Say that the system manager finds that he often has to
do a :REPLY or a :STARTSPOOL when logged on as various user IDs -- without GOD,
he'll be quite likely to :ALLOW these commands globally since there would
otherwise be no way for him to access these commands.  If he has GOD, he can
avoid :ALLOWing these commands because he will always have them available (if
he knows the GOD lockword).

Similarly, if the system manager finds himself needing various programs or data
files when he logs on as non-SM users, he will be tempted to :RELEASE these
files or otherwise keep them less secure than they should be.  If he uses GOD,
he will always be able to access any file he needs -- again, only if he knows
the GOD lockword.

However, since we realize that GOD could conceivably be quite dangerous if
improperly secured, we give you several ways of protecting it from unauthorized
access:

   * First and foremost, you should always keep GOD under a lockword.  If you
     put our installation tape onto your machine, our installation procedure
     will automatically choose a RANDOM lockword for GOD (unless you have a
     lockword on it already, in which case we'll keep the lockword the same as
     it was).

   * The $GOD-RESTRICT keyword of the SECURCON.DATA.VESOFT file can be used to
     restrict who can run GOD -- for instance, if you say


GOD-RESTRICT, SECURCON file keyword ``restrict
$GOD-RESTRICT, SECURCON file keyword

          $GOD-RESTRICT RYAN,@.@ ANNE,@.@

     then only users who are logged on with session names RYAN or ANNE will be
     allowed to run GOD.  You can then set up SECURITY passwords for RYAN,@.@
     and ANNE,@.@ to make sure that only the right people will be able to log
     on with these session names.

     Remember that users who have $GOD-RESTRICT set for them must still know
     the GOD lockword to run it.

   * The $LOG-GOD keyword of the SECURCON.DATA.VESOFT indicates that any time
     GOD is run, it will write a record to the SECURITY log file.  If you say


LOG-GOD, SECURCON file keyword ``god
$LOG-GOD, SECURCON file keyword

          $LOG-GOD @.@-APBUILD,BATCH.AP

     then GOD will write a log record whenever it is run by anybody except for
     the job stream APBUILD,BATCH.AP.  (This can be useful if APBUILD,BATCH.AP
     has to run GOD to get a capability or an :ALLOW that it needs -- you might
     want this not to generate log records because it is a normal, expected
     occurrence.)

     The log records will indicate where GOD successfully granted the
     capabilities and :ALLOWs or whether it refused to do this (because of
     $GOD-RESTRICT or $GOD-MOVABLE).


GOD-MOVABLE, SECURCON file keyword ``movable
$GOD-MOVABLE, SECURCON file keyword

  * Because some users have requested this, GOD.PUB.VESOFT can not normally be
     copied out of the VESOFT account.  (If it is, it'll print an error message
     whenever it's run.) This prevents users from possibly copying GOD into
     some other place where it might be difficult for the system manager to
     find.

     We've always thought that this wasn't a serious issue, since GOD will only
     run when it's kept in a privileged group, and anybody who can copy files
     into a privileged group can break system security anyway.  However, our
     users asked for this and our accountants told us that if we wanted to make
     money, we should listen to what our users say.  Thus, GOD can normally be
     kept only in the VESOFT account.

     If you want to move GOD out of the VESOFT account -- perhaps because you
     want to keep it in a less visible place -- you can say (in the
     SECURCON.DATA.VESOFT file):

        $GOD-MOVABLE ON

   * Finally, if you really want to, you can purge GOD.PUB.VESOFT altogether.
     We don't think that this is necessary or desirable, but you can do this if
     you wish.

AVOIDING SOME POSSIBLE MPE SECURITY LOOPHOLES


Avoiding some possible MPE security loopholes ``contents
Avoiding some possible MPE security loopholes

There are a few MPE security loopholes that you need to avoid in order to take
full advantage of SECURITY.  If you do not eliminate these problems, some
knowledgeable people might be able to exploit them to compromise your system
security by overriding MPE's normal logon UDC handling.

What you must do is:


COMMAND.PUB.SYS, protecting it
COMMAND.PUB.SYS, see also report #105 in the VEAUDIT manual

  * :ALTSEC COMMAND.PUB.SYS;(L,X:ANY) -- see the VEAUDIT manual's section #105
     for more information.  This should not adversely impact anything else
     unless you use a program that requires Read access to COMMAND.PUB.SYS
     (which a few programs, including the /SET UDC command of ROBELLE's QEDIT,
     do); if you have such a program, you can use the CMDPROT task under the
     BACKG job (please see %BACKG in the "MPEX Commands" section of the MPEX
     User Manual for details).


:DSLINE ;LOGON= ``ns`autologon
:DSLINE ;LOGON=
NSCONTROL AUTOLOGON, security concerns

  * If you use NS/3000, do an :NSCONTROL AUTOLOGON=OFF,ALL -- this should not
     adversely impact you unless you use the :DSLINE ;LOGON= syntax or you use
     NS/VAX.


TMPCONVP.CONVALL.SYS, protecting it (MPE/V systems only)

  * :ALTSEC TMPCONVP.CONVALL.SYS;(X:CR) -- on MPE/V, HP provides this program
     as part of the IMAGE-to-TurboIMAGE conversion.  By default, anyone on the
     system can run it, and it can be used to bypass some system security.

We do not want to give any more details on these things in this public
document; please call us if you have any further questions.


Changing the capacity of the SECURG file``contents`news`secload
Changing the capacity of the SECURG file

Normally, you would use the %SEC SECURCAP command to change the capacity of the
file SECURG.DATA.VESOFT.  Since increasing the file limit will increase the
capacity of most internal datasets, this command will be sufficient for most
sites.  However, the maximum number of profiles that the file can ever contain
is determined at the time the file is built.  By default, this limit is around
11,000 profiles.

If you plan on adding more profiles than this, you must purge the SECURG file
and rebuild it with a higher maximum.  In order to do this, you must enter the
following commands:

  %SEC SECDUMP;OUT=filename

  %RENAME SECURG.DATA.VESOFT, SECUROLD.DATA.VESOFT
          - or -
  %PURGE SECURG.DATA.VESOFT

  %SEC SECLOAD;IN=filename;MAXPROFILES=profile limit[;FLIMIT=flimit]

The %SEC SECLOAD command will automatically rebuild the datafile using the
;MAXPROFILES and ;FLIMIT settings supplied.  These parameters will only take
effect if the SECURG data file does not exist at the time you enter the
command, so the original SECURG file must be purged or renamed.  (RENAMEing is
safer since the file can be quickly recovered in the event of an unexpected
error, such as running out of disk space when building the new file).  Since
SECURG is a PRIV file, you will need to use MPEX to purge or rename the file.
(If you don't own MPEX, contact our technical support department for assistance
when purging PRIV files).

You may use any legal MPE filename for the name of the workfile to store the
current profiles and other security related data.  The %SEC SECLOAD command
does not purge this workfile, so after this command is finished, the workfile
should be manually purged from the system.  Note that the absolute limit for
the profile limit is 32,767, but the FLIMIT can (and should) be higher.  The
;FLIMIT parameter is only needed if the current FLIMIT of the SECURG file is
over 9999 or if you intend to add a large number of profiles immediately after
you have built the SECURG data file.  If this parameter is not supplied, the
file will be built with a default FLIMIT which can be increased at a later date
using the %SEC SECURCAP command.  However, if you intend to add all or nearly
all the profiles after you have increased the profile limit, you should set the
FLIMIT to 20% more than the profile limit.

The %SEC SECLOAD command will fail if any users or jobs are accessing the file,
which includes users in a SECURITY menu, jobs just logging on to the system,
and anyone streaming a job using STREAMX.


SECURITY's logging facility ``contents
SECURITY's logging facility
LISTLOG, MAIN.PUB.VESOFT entry point

Would you ever like to see who added a particular SECURITY user profile? When a
certain user has logged on to the system? Who logged on to the system this
weekend? What attempted security violations have occurred in the past month?

SECURITY keeps a very thorough log file and gives you very flexible reporting
capabilities.  In particular, SECURITY logs:

   * All SECURITY user profiles maintenance commands (ADD, CHANGE, DELETE and
     REACTIVATE).

   * All logons (an option you may turn on or off using the $LOG-LOGON
     keyword).

   * All job stream submissions performed via STREAMX (an option you may turn
     on or off using the $LOG-STREAM keyword).

   * All times that an MPE user changed his own password by doing a :RUN
     MAIN.PUB.VESOFT,PASSWORD (perhaps by using our :PASSWORD UDC).

   * At the account or system manager's discretion, a menu file might cause
     manager-specifiable data to be logged (e.g.  the fact that a user executed
     a specific menu option).

   * User-specified events, using the VELOG command (in SECURITY menus) or the
     SECURITYLOG(...) function.

To examine this log file, you say

   :RUN MAIN.PUB.VESOFT,LISTLOG

   SECURITY/LISTLOG 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   Enter selection criteria (CR to print all, ? for help):    << hit CR >>
   Sort by (CR to sort by date and time, ? for help):    << hit CR >>
   Listing to (L)ine printer or (T)erminal? T
   VESOFT SECURITY Log file listing on SAT, 21 NOV 88
    Type :  Date    Time  Dev Logon                Target user/
                                                   Violation type
   Logon :29OCT88 11:59AM 32  DAN,MOVILINE.LIST    OK LOGON
   Violat:29OCT88 12:51PM 31  BORIS,STUDENT.SALES  BAD PASSWORD
   Logon :29OCT88 12:51PM 31  BORIS,STUDENT.SALES  OK LOGON
   Change: 2NOV88  8:47AM 24  JEFF,MANAGER.LIST    SASHA,LOOKUP.LIST
   Add   : 2NOV88  8:47AM 24  JEFF,MANAGER.LIST    MARINA,LOOKUP.LIST
   Violat: 2NOV88 11:49AM 22  SIMON,MANAGER.SYS    BAD TERMINAL PASSWORD
   ...

As you see, every log record is displayed together with:

   * Its type (LOGON, VIOLATion, ADD, CHANGE, DELETE, REACTIVATE, MENU, STREAM,
     etc.).

   * The date of the event being logged.

   * The time.

   * The terminal on which it occurred.

   * The user who is logging on, attempting to log on or the user performing
     the operation (for ADD, CHANGE, DELETE, and REACTIVATE records); the
     session, user, and account are shown -- when output is sent to the line
     printer, the group is shown as well.

   * The user name (from the SECURITY user profile) of the user logging on or
     performing the operation (if available) -- this is only output when you
     ask for a report to the line printer.

   * Further information on the record, including:

     - For violation records, the type of violation (BAD TERMINAL, BAD
       PASSWORD, etc.).

     - For logon records, "OK LOGON", optionally followed by an indication of
       which terminal password was used to log on (see the Multiple Terminal
       Passwords chapter above).

     - For ADD, CHANGE, DELETE, and REACTIVATE records, the user being added,
       changed, deleted or reactivated.

     - For MENU records, the log text specified in the menu's VELOG command
       (see the Logon Menus Revisited chapter below).

SELECTING LOG RECORDS TO BE LISTED


Selecting log records to be listed ``contents
Selecting log records to be listed
SECURITY log file record attributes

As you can guess, the log file output can get pretty large.  You have to have
some kind of selection capability that lets you extract exactly those records
that you want to see.

If you hit [RETURN] (as we did in the above example) in response to the "Enter
selection condition:" prompt, you'll get a listing of all the log records (if
you have SM capability) or of all the log records pertaining to your account
(if you have AM capability but not SM capability).

However, you can also specify an arbitrary logical expression which can involve
operators like +, -, *, /, =, <, >, <=, >=, <>, AND, OR, NOT, etc., and some
specially-defined variables:


OPADD, selecting SECURITY add log records
              [BOOL]    TRUE if this record is for an ADD operation


OPCHANGE, selecting SECURITY change log records
           [BOOL]    TRUE if CHANGE operation log record


OPCHLOGON, selecting SECURITY chlogon log records
          [BOOL]    TRUE if CHLOGON operation log record


OPDELETE, selecting SECURITY delete log records
           [BOOL]    TRUE if DELETE operation log record


OPNETADD, selecting SECURITY network add log records
           [BOOL]    TRUE if this record is for an ADD operation
                              performed by NETRECV


OPNETCHANGE, selecting SECURITY network change log records
        [BOOL]    TRUE if this record is for a CHANGE operation
                              performed by NETRECV


OPNETDELETE, selecting SECURITY network delete log records
        [BOOL]    TRUE if this record is for a DELETE operation
                              performed by NETRECV


OPVIOLATION, selecting SECURITY violation log records
        [BOOL]    TRUE if attempted violation log record


OPDEACTIVATE, selecting SECURITY deactivation log records
       [BOOL]    TRUE if DEACTIVATE operation log record


OPREACTIVATE, selecting SECURITY reactivation log records
       [BOOL]    TRUE if REACTIVATE operation log record


OPLOGON, selecting SECURITY logon log records
            [BOOL]    TRUE if logon log record ($LOG-LOGON must be set
                              in SECURCON to enable this)


OPPASSWORD, selecting MPE password change log records
         [BOOL]    TRUE if PASSWORD operation log record


OPVEPASSWORD, selecting SECURITY password change log records
       [BOOL]    TRUE if SECURITY PASSWORD operation log record


OPMENU, selecting SECURITY menu log records
             [BOOL]    TRUE if menu log record


OPSTREAM, selecting SECURITY job stream log records
           [BOOL]    TRUE if stream log record ($LOG-STREAM must be
                              set in SECURCON to enable this)


OPMANUAL, selecting records logged by SECURITYLOG function ``manual
OPMANUAL, selecting records logged by SECURITYLOG function
           [BOOL]    TRUE if record logged by the SECURITYLOG function
                              being called from an MPEX command file, a STREAMX
                              :: command or some other such context


OPGOD, selecting GOD execution log records
              [BOOL]    TRUE if record logged by the GOD program
                              ($LOG-GOD must be set in SECURCON to enable this)


OPGODRESTRICT, selecting GOD restriction violations
      [BOOL]    TRUE if record was logged by the GOD program
                              because a user who ran GOD was forbidden to do it
                              by $GOD-RESTRICT.


DATE, selecting SECURITY log records by
               [DATE]    date of the event being logged


TIME, selecting SECURITY log records by
               [TIME]    time of the event being logged


TERMINAL, selecting SECURITY log records by
           [INT]     LDEV# of terminal on which event occurred


ACCOUNT, selecting SECURITY log records by
            [STR]     account name of user involved


USER, selecting SECURITY log records by
               [STR]     user name of user involved


SESSION, selecting SECURITY log records by
            [STR]     session name of user involved


GROUP, selecting SECURITY log records by
              [STR]     group name of user involved


NAME, selecting SECURITY log records by user real name
               [STR]     real name of user involved


VIOLATION, selecting SECURITY log records by violation type
          [STR]     for violation log records, the type of the
                              violation (e.g.  "BAD PASSWORD")


TARGETACCOUNT, selecting SECURITY log records by ``account
TARGETACCOUNT, selecting SECURITY log records by
      [STR]     for add/change/delete/reactivate log records, the
                              account name of the user being operated on


TARGETUSER, selecting SECURITY log records by ``user
TARGETUSER, selecting SECURITY log records by
         [STR]     the user name of the user operated on


TARGETSESSION, selecting SECURITY log records by ``session
TARGETSESSION, selecting SECURITY log records by
      [STR]     the session name of the user operated on


QUALIFIER, selecting SECURITY log records by
          [STR]     for logon records, the string "OK LOGON" or "OK
                              LOGON, TERMPASS#N" (if a terminal password was
                              prompted for and the Nth password was input in
                              response); for menu VELOG records (type OPMENU)
                              and manually logged records (type OPMANUAL), the
                              user-specified text

As you can see, every one of these variables has a "datatype" of INTEGER,
STRING, BOOLEAN, DATE or TIME, which dictates what you can do with it (for
instance, you can't compare an integer with a string).  The various operators
defined on these variables are discussed in greater detail in Appendix;
however, some good examples should be rather obvious:

   Enter selection condition: OPADD or OPCHANGE or OPDELETE

     shows only the ADD, CHANGE, and DELETE log records

   Enter selection condition: ACCOUNT="PROD"

     shows only the records pertaining to the PROD account

   Enter selection condition: DATE=88/12/09

     shows only the records logged on the 9th of December, 1988

   Enter selection condition: OPVIOLATION AND VIOLATION="BAD PASSWORD"

     shows only violation records where the cause of violation was a bad
     SECURITY password

   Enter selection condition: OPLOGON AND (TERMINAL=61 OR TERMINAL=62)

     shows all logons on LDEVs 61 and 62

   Enter selection condition: OPLOGON AND DATE>(TODAY-30)

     shows all logons for the past 30 days

The possibilities are virtually endless -- you can select exactly those records
that you want to see.

SORTING THE SECURITY LOG LISTING


Sorting the SECURITY log listing ``contents
Sorting the SECURITY log listing

By default, the listing comes out sorted in ascending order by date and time.
You can change this by responding differently to the "Sort by: " prompt:

   Sort by: TERMINAL, DATE, TIME

will sort by the terminal number on which the event being logged took place,
and then within each terminal by date and time.  Similarly,

   Sort by: ACCOUNT:8, USER:8, SESSION:8, DATE, TIME

will sort by account, by user, by session, by date, and by time.  Note that we
had to specify a ":8" after the ACCOUNT, USER, and SESSION variables -- this is
because they are string variables; when the sort keys are strings, we must
specify the length of each string being sorted by (maximum is 8 for ACCOUNT,
USER and SESSION, 30 for NAME and QUALIFIER).

If you want to sort in descending order, you should say

   Sort by: DATE:'DESC', TIME:'DESC'

The ":'DESC'" suffix indicates descending order.

INDICATING A SYSTEM NAME FOR REPORT HEADINGS

If you have more than one computer, you'll probably want to have the LISTLOG
(and LISTUSER) printouts indicate which computer they pertain to.  SECURITY
lets you specify your "system name" to be put into your LISTLOG and LISTUSER
report headings.  For more information on this, see the subsection "Indicating
A System Name For Report Headings" in the section "Listing User Profiles" in
this manual.

WHERE THE LOG RECORDS ARE KEPT


Where the log records are kept ``contents
Where the log records are kept
LOG20.DATA.VESOFT, SECURITY log file

All these log records are kept in the file LOG20.DATA.VESOFT, which is a
circular file.  We initially build it to have 5000 records, and since it's
circular, it always keeps the most recent 5000 records -- once it reaches 5000
records, each new log record causes the oldest one to be thrown away.

If you want to increase (or decrease) the number of log records kept, you can
just alter the file limit, either by copying it and renaming it or (much more
easily) by using MPEX to say

   :RUN MAIN.PUB.VESOFT
   %ALTFILE LOG20.DATA.VESOFT; FLIMIT=10000


LOG-LOGON, SECURCON file keyword ``logon
$LOG-LOGON, SECURCON file keyword
$LOG-STREAM, SECURCON file keyword
'll probably find that the majority of your log records will be logon and
stream records.  What if you don't want to keep track of logons or streams or
perhaps only want to log logons and streams in especially sensitive accounts?
No problem! The SECURCON.DATA.VESOFT keywords $LOG-LOGON and $LOG-STREAM let
you restrict logon and stream logging very specifically.  For instance,

   $LOG-LOGON OFF
   $LOG-STREAM OFF

will turn off logging of logons and streams altogether;

   $LOG-LOGON @.AP&ONLINE @.DEV&ONLINE LDEV=61 LDEV=62

will only log online (session) logons to the AP and DEV accounts and also any
logons on terminals 61 and 62;

   $LOG-STREAM @.@-@.DEV-OPERATOR.SYS

will log the submission of streams by any user except users in the DEV account
and OPERATOR.SYS.

CLEARING THE SECURITY LOG FILE


Clearing the SECURITY log file ``contents
Clearing the SECURITY log file

Of course, there's a lot to be said for logging as much as possible and then
ignoring the things you don't want using LISTLOG's powerful selection
conditions.  On the other hand, the $LOG-LOGON and $LOG-STREAM can be useful to
make your life simpler if you know you'll never need the logging information
that you disable.  If you want to entirely clear out the log file -- throw away
all the records currently inside it -- you can simply say


CLEARLOG, MAIN.PUB.VESOFT entry point ``logging
CLEARLOG, MAIN.PUB.VESOFT entry point

   :RUN MAIN.PUB.VESOFT,CLEARLOG

This option (which, naturally, can only be executed by an SM user) will get rid
of all the records in the log file.


LOG20.DATA.VESOFT file, report on a copy of it
users like to make a COPY of the log file before clearing it.  If you do
this, you can still use LISTLOG to generate reports on the copy by issuing the
:FILE-equation before running LOGON,LISTLOG:

   :FILE LOG20.DATA.VESOFT=mylogfilename

where "mylogfilename" is the name of the log file you wish to report on.  For
security reasons, this :FILE-equation will only be honored if you have SM
capability.


Logon menus revisited: a detailed explanation ``contents
Logon menus revisited: a detailed explanation

One of the things that you can specify in a SECURITY user profile is a logon
menu file.  If you specify it, then when that user logs on, he won't get direct
access to MPE -- instead, he'll be shown the menu and asked to select one of
the options specified inside it.

To set up a menu for a user, the account or system manager must:

   1.      Build the menu file.

   2.      Make sure that the user has $VEPROFILE configured for him (the menu
      file name is part of a user's SECURITY profile).

   3.      Add a user profile for that user (or change his existing user
      profile) to include that menu file name.

Points 2 and 3 are discussed in the Logon Menus chapter above; the rest of this
section will talk about how you should build a menu file.

A menu file is a simple EDITOR-type file.  The purpose of the menu file is to
indicate what things a user for whom this menu file is set can do.

Let's take a very simple example of a menu file:

   :EDITOR
   /ADD
       1     *HEADER A TEST MENU
       2     *CAPTION   SHOW THE CURRENT TIME
       3        SHOWTIME
       4     *CAPTION   SHOW HOW YOU ARE LOGGED ON
       5        SHOWME
       6     *CAPTION   RUN THE EDITOR
       7        EDITOR
       8     *CAPTION   PRINT THE NAMES OF ALL YOUR FILES TO THE PRINTER
       9        FILE LP;DEV=LP
      10        LISTF ;*LP
      11        RESET LP
      12     //
   /KEEP MYMENU,UNN; EXIT

If you set up this file as the logon menu file for a user, then when the user
logs on, he'll see this:

   :HELLO JOE,TEST.DEV
                    .  .  .
   PLEASE ENTER THE SECURITY PASSWORD:

   Welcome!  You are now signed on.

   A TEST MENU
     1.  SHOW THE CURRENT TIME
     2.  SHOW HOW YOU ARE LOGGED ON
     3.  RUN THE EDITOR
     4.  PRINT THE NAMES OF ALL YOUR FILES TO THE PRINTER

   Enter selection (or E to EXIT, R to REDISPLAY or L to LOCKUP): 1

   TUE, NOV 24, 1988,  3:41 PM    <<:SHOWTIME output is displayed>>

   A TEST MENU
     1.  SHOW THE CURRENT TIME
     2.  SHOW HOW YOU ARE LOGGED ON
     3.  RUN THE EDITOR
     4.  PRINT THE NAMES OF ALL YOUR FILES TO THE PRINTER

   Enter selection (or E to EXIT, R to REDISPLAY or L to LOCKUP): 3

   HP32201A.07.17 EDIT/3000 TUE, NOV 24, 1988,  3:41 PM
   (C) HEWLETT-PACKARD CO.  1985
   /    << You're now in editor >>
   ...
   /EXIT

   A TEST MENU
     1.  SHOW THE CURRENT TIME
     2.  SHOW HOW YOU ARE LOGGED ON
     3.  RUN THE EDITOR
     4.  PRINT THE NAMES OF ALL YOUR FILES TO THE PRINTER

   Enter selection (or E to EXIT, R to REDISPLAY or L to LOCKUP): E

   END OF PROGRAM

   CPU SEC.  = 45.  ELAPSED MIN.  = 2.  TUE, NOV 24, 1988, 3:43 PM

Note how the menu facility works:

   * When the user logs on, the menu is displayed (all the *HEADER and *CAPTION
     lines from the menu are printed to the screen).

   * The user is prompted for one of those selections, E to exit, R to
     redisplay or L to lockup (secure) his session.

   * When a user enters a selection, the MPE commands defined in the menu for
     that selection are executed.

   * After the execution of the MPE commands for the selection is done, the
     menu is redisplayed and a new selection is prompted for.

   * When the user hits E, he is logged off.

A menu file should look something like this (things surrounded by [ and ] are
OPTIONAL):


*HEADER, logon menu keyword
*START, logon menu keyword
*CAPTION, logon menu keyword
*FINISH, logon menu keyword

   [ *HEADER first line of header                         ]
   [ ...                                                  ]
   [ *HEADER last line of header                          ]
   [ *START                                               ]
   [ commands to be executed when the menu FIRST comes up ]
   [ ...                                                  ]
   *CAPTION text to be output for selection 1
   commands to be executed when selection 1 is requested
   ...
   *CAPTION text to be output for selection 2
   commands to be executed when selection 2 is requested
   ...
   *CAPTION text to be output for selection N
   commands to be executed when selection N is requested
   [ *FINISH                                              ]
   [ commands to be executed when the user types E to exit]
   [ ...                                                  ]

(If necessary, *menukeyword lines may be continued on the next physical line by
adding an "&" at the end of the line to be continued.)

In other words, the menu file may include:


*START, used to execute ACCOUNT level OPTION LOGON UDCs

  * An optional *START section indicating which commands are to be executed
     when the menu is first displayed (not on each subsequent redisplay).
     Since users configured to use a menu do not actually execute the ACCOUNT
     or USER level OPTION LOGON UDC, this section should contain the same
     commands that are in the ACCOUNT or USER level OPTION LOGON UDCs set for
     each user.

   * One *HEADER line for each line that you want to output at the top of the
     displayed menu as a menu header.

   * For each thing that you want to let a user do, a *CAPTION line indicating
     how that thing will be described in the menu and one or more MPE commands
     indicating what is to be done when that selection is executed.

   * An optional *FINISH section indicating which commands are to be executed
     when the user hits E to exit the menu.

What commands can be contained in each *CAPTION section and the *START and
*FINISH sections? Well, virtually any, and then some.  This includes:

   * Almost all normal MPE commands (whether executable using the COMMAND
     intrinsic or not)! This includes :SHOWTIME, :SHOWJOB, :FILE, :RUN,
     :EDITOR, :COBOL, :IF/:ELSE/:ENDIF, etc.

     In addition, MENUs running on CLASSIC (MPE/V) systems can use most of the
     MPE/iX commands and constructs (including CHGROUP, INPUT, PRINT, ECHO,
     WHILE, etc.)!


MPEX commands, executing them in SECURITY menus

  * Any MPEX command (if you are an MPEX user), by simply prefixing it with a
     "%"! For example:


%commandname, executing MPEX commands in menus

        %ALTFILE MYFILE;SQUEEZE

     (See the MPEX User Manual for details on MPEX commands.)


MENUMGR files

    Before executing the first % command, LOGON will execute the commands in
     the file MENUMGR.PUB.VESOFT (similar to MPEXMGR.PUB.VESOFT).  If
     MENUMGR.PUB.VESOFT contains an INITMPEXMGR command, it will also execute
     the commands in MENUMGR.PUB.logonacct and MENUMGR.logongrp.logonacct.


SEC commands, executing them in SECURITY menus

  * SECURITY maintenance commands, by using the SEC prefix! (See
     "Command-driven SECURITY Maintenance", in this manual.)


VEAUDIT command, executing them in SECURITY menus

  * VEAUDIT commands (if you are a VEAUDIT user), by using the VEAUDIT prefix!
     (See "Accounting Structure Maintenance" in the VEAUDIT User Manual.)


UDCs in SECURITY menus

  * All UDCs!  (However, please see the chapter Speeding Up Logons elsewhere
     in this manual.)


CHGROUP, switching groups in SECURITY menus

  * The command CHGROUP, which allows you to switch to another group without
     having to exit the menu and re-logon (this command is fully documented in
     the MPEX User Manual).


CHLOGON, switching logons in SECURITY menus

  * The command CHLOGON, which allows you to switch to another
     session,user.account,group without having to exit the menu and re-logon
     (this command is fully documented in the MPEX User Manual).


WITHCAPS, granting extra capabilities in SECURITY menus

  * The command WITHCAPS, which allows you to temporarily, in a controlled
     way, give a user extra capabilities (this command is also fully documented
     in the MPEX User Manual).

   * The command


VEMENU, logon menu pseudo-command

        VEMENU filename

     which indicates that the given menu file is to be displayed and the user
     is to be allowed to select options from that menu file.  When the user
     types E to get out of that menu file, control will return to the current
     menu.

   * The command BYE, which gets the user out of this menu and all the ones
     above it, and logs him off the system.

   * The command


VELOG, logon menu pseudo-command

        VELOG text

     which writes the given text as a log record into the SECURITY log file.  A
     subsequent :RUN MAIN.PUB.VESOFT,LISTLOG will display this record together
     with all other SECURITY log records.  This command is useful for keeping
     an audit trail of all the things a user did.

Thus, a sophisticated logon menu file might look like:

   *HEADER ACCOUNTS PAYABLE CLERK MENU
   *HEADER
   *START
      FILE APBASE=APBASE.DATA.AP
      RUN APWELCOM.PUB.AP
   *CAPTION    DO VENDOR MAINTENANCE
      VELOG DOING VENDOR MAINTENANCE
      RUN APVM001.PUB.AP;LIB=G;PARM=7
   *CAPTION    DO INVOICE MAINTENANCE
      VELOG DOING INVOICE MAINTENANCE
      RUN APIM001.PUB.AP;LIB=G;PARM=7
   *CAPTION    ENTER GENERAL LEDGER SUBMENU
      VEMENU GLMENU.DATA.GL
   *CAPTION    PRINT A FILE TO THE LINE PRINTER
      FILE LP;DEV=LP;CCTL
      FCOPY FROM=?ENTER FILE NAME?;TO=*LP
   *CAPTION    SHOW STATUS OF ALL RUNNING JOBS
      SJ EXEC
   *FINISH
      RUN APEXIT.PUB.AP

As you see, the above menu file does VELOGs to log text into the SECURITY log
file, calls a submenu, does :RUNs, and even a UDC (SJ EXEC).

You might also have noticed a line that says:

   FCOPY FROM=?ENTER FILE NAME?;TO=*LP

This will prompt the user for a file name:

   ENTER FILE NAME? XXX

and will substitute the user's response ("XXX") in place of the text between
the question marks; thus, the command executed will be

   FCOPY FROM=XXX;TO=*LP

This is a very powerful feature, and we could discuss it for pages; however,
we'd rather just refer you to the Batch Access Security...  chapter of this
manual.  STREAMX uses exactly the same feature to allow you to build smart job
streams and this is discussed in great detail in that chapter.  (The menu
facility supports not only "?...?" prompts but also "..." constructs and the
PROMPT, ASSIGN, ECHO and WHILE commands (but without the "::" prefix!).)

One other feature that bears mentioning: often, you'll want to use a menu not
just at logon time, but also from an already logged-on session.  The best
example is when you're developing a menu and want to check it to make sure it
does what you want; another case is when you want to put some useful options
into a menu and have a user use it not for security but for convenience.

To do this, you can say:


MENU, MAIN.PUB.VESOFT entry point
MENUFILE, file equation for LOGON,MENU

   :FILE MENUFILE=filename
   :RUN MAIN.PUB.VESOFT,MENU

SECURITY will display the menu and let you execute any of the options
configured within it; when you hit E, it'll drop you back into MPE (rather than
log you off, which would be the case if you got this menu at logon time).

Note that in this mode, if (for some reason) you include a BYE command within a
*CAPTION, it will simply drop you back into MPE; it won't actually log you off.

Finally, one other consideration.  To support UDC execution from within menus,
we have to open and read your UDC files every time a user logs on; on a
heavily-loaded system, this can add 5-10 seconds to the logon time.

If you find this to be a problem, you can add to your SECURCON.DATA.VESOFT file
the line:


MENU-UDC, SECURCON file keyword ``UDC
$MENU-UDC, SECURCON file keyword

   $MENU-UDC OFF

This will tell SECURITY that all logon menus will never execute UDCs; then,
SECURITY can avoid reading the UDC files and save some time at logon.  You can,
of course, be more selective:

   $MENU-UDC @.@-@.AP-@.GL

says that UDCs will be allowed in the logon menus of all users except those in
the AP and GL accounts.  The menus for AP and GL users may not have UDCs, and
whenever an AP or GL user logs on, SECURITY won't read his UDC files.

IN CASE OF STACK OVERFLOW


What to do if MAIN.PUB.VESOFT gets a "stack overflow"
, if you nest menus within each other deeply enough (with "VEMENU"
commands), MAIN.PUB.VESOFT will get a stack overflow; each level of nesting
requires MAIN.PUB.VESOFT to keep track of extra information, and eventually MPE
refuses to give LOGON the space to keep this data.

(Note that SECURITY can not cause stack overflows in your own programs that you
run from within it -- if you get a stack overflow in one of your own programs,
it's caused by excessive stack usage in that program.  This section only
discusses stack overflows in MAIN.PUB.VESOFT itself.)

There are two things that you can do about this condition:

   * As we mentioned above, the menu facility lets you use the ?xxx? and xxx
     syntaxes (as well as the PROMPT and ASSIGN) commands that you can use in
     STREAMX job streams.  These syntaxes allow you to define variables, and we
     allocates space for such variables for each level of menu file nesting.

     Unfortunately, at the time we allocate this variable space, we can't know
     how many variables you'll be using (if any), so we always allocate 1024
     words of space.  Sometimes (if you have many variables in your menu) this
     may not be enough; sometimes it may be too much.

     By saying


SECURITYMENUVARAREASIZE, SECURITY JCW ``menu`overflow
SECURITYMENUVARAREASIZE, SECURITY JCW

        :SETJCW SECURITYMENUVARAREASIZE = value

     you can change the amount of space we allocate for variables; you can
     increase it (if you're getting "Error: Variable area overflow" error
     messages) or decrease it (if you're getting stack overflows).

     This :SETJCW takes effect for all the menus that are brought up after the
     command is executed.  Thus, if you put it in the *START section of a menu
     file, that menu will have the default (1024 words) allocated for it, but
     all menus executed from within it will have allocated the amount of space
     indicated by the :SETJCW.  If you put the :SETJCW into your SECURCON.DATA
     file (via $LOGON-EXECUTE), it will take effect for all menus.

   * Alternatively, instead of saying (in your menu file)

        VEMENU filename

     you can say

        FILE MENUFILE=filename
        RUN MAIN.PUB.VESOFT,MENU

     This will cause an entirely new MAIN.PUB.VESOFT process to be started up
     -- since this process has its own stack, there will be plenty of room on
     it for more data (including more VEMENU nestings).  The only disadvantage
     of this approach is that it is a bit slower (since it takes time to create
     the extra son process).

LOGON MENUS AND :REMOTE HELLOs


Logon menus and :REMOTE HELLOs ``contents
Logon menus and :REMOTE HELLOs

You can tell VEMENU to automatically insert remote passwords into REMOTE HELLO
commands (of course, in a controlled, secure fashion), thus avoiding both
unnecessary password prompts and the need to embed passwords in your menu
files.

For more information on this, see the chapter on REMOTE HELLO Processing In
Logon Menus And In MPEX in the STREAMX portion of this manual.


Logon menus: advanced features ``contents
Logon menus: advanced features

CONTROLLING MENU DISPLAY FORMAT


Logon menus: Controlling menu display format ``contents
Logon menus: Controlling menu display format


Multi-column menus
default, logon menus are displayed with one caption per line, each caption
prefixed by its caption number.  For instance, if your menu file says

     *CAPTION AGING REPORT
     ...
     *CAPTION VENDOR MAINTENANCE
     ...
     *CAPTION INVOICE MAINTENANCE
     ...

the menu will be displayed as:

     1.  AGING REPORT
     2.  VENDOR MAINTENANCE
     3.  INVOICE MAINTENANCE

What if you want to display the menu differently? In particular, what if you
have more than 24 options -- more than can fit on a screen -- and you want to
display in, say, two columns? We let you do this; in fact, we let you specify
exactly how you want the menu displayed.

As you may know, the xxx syntax of STREAMX is also accepted in SECURITY
menus.  Thus, you can say (as a line in one of your menus)

   ECHO 2+3

and the expression 2+3 will be evaluated and displayed with the ECHO command.
Saying "ECHO 2+3" is really the same as saying "ECHO 5" -- any expression
between a "" and a "" gets evaluated and gets replaced by its result.

Well, two of the functions that you can use between a "" and a "" are TERMPOS
and TERMCLEAR.  The function TERMPOS, used, for instance, in

   *HEADER termpos(1,20)ACCOUNTS PAYABLE MENU

returns a string that positions the cursor at a particular row and column
position on an HP terminal (in this case, row 1, column 20).  The menu
processor sees the "TERMPOS(1,20)", evaluates the expression "TERMPOS(1,20)",
and substitutes the result of the expression into the *HEADER line.

Then, the *HEADER command gets executed, and outputs its parameters -- which
are now the escape sequence that positions the cursor at row 1, column 20,
followed by the string "ACCOUNTS PAYABLE MENU" -- as a header.  The result is
that "ACCOUNTS PAYABLE MENU" is displayed starting at row 1, column 20.

The TERMCLEAR function returns an escape sequence that clears all of the screen
starting with the current cursor position.  Thus,

   *HEADER termpos(0,0)termclear()        MAIN MENU

will position the cursor in row 0, column 0, clear the screen, and then display
the string "        MAIN MENU".

Note that the TERMCLEAR function was written as "TERMCLEAR()", not as
"TERMCLEAR".  The open and close parentheses are necessary to identify
TERMCLEAR as a function (rather than a variable).  If you omit the parentheses,
SECURITY will try to find a JCW or an MPE/iX variable -- since it probably
won't find it, you'll get an error message.

So, now that you have the TERMPOS and TERMCLEAR functions, it should be easy
for you to format the menu any way you like it.  For instance, you might say:

   *HEADER termpos(0,0)termclear()
   *HEADER termpos(1,35) MAIN MENU
   *CAPTION termpos(4,5) AGING REPORT
   ...
   *CAPTION termpos(7,5) VENDOR MAINTENANCE
   ...
   *CAPTION termpos(7,40) INVOICE MAINTENANCE
   ...

This way, the header and the captions will come out exactly where you want
them.  Right?

Well, almost right.  The only problem is that *CAPTION outputs the option
number before outputting the *CAPTION parameter.  Thus, the first *CAPTION
would output the "1." wherever the cursor happened to be, then position the
cursor in row 4, column 5, and then output "AGING REPORT" -- not exactly what
we had in mind.


*CAPTIONL, logon menu keyword
MENUOPTION, logon menu option number variable
this case, *CAPTION's automatic insertion of the option number is working
against us.  What we must do is use the *CAPTIONL command (the "L" in
"CAPTIONL" stands for "Literal") which outputs the remainder of the line
without preceding it with the option number.  But, since we do want to output
the option number (we just want to output it after the escape sequence), we'll
just use the special variable "!MENUOPTION" (which is set to the option number
of the current *CAPTION/*CAPTIONL) in the *CAPTIONL line at the place where we
want the option number output.

Thus, our menu file might look something like this:

   *HEADER termpos(0,0)termclear()
   *HEADER termpos(1,35) MAIN MENU
   *CAPTIONL termpos(4,5) !MENUOPTION   AGING REPORT
   ...
   *CAPTIONL termpos(7,5) !MENUOPTION   VENDOR MAINTENANCE
   ...
   *CAPTIONL termpos(7,40) !MENUOPTION   INVOICE MAINTENANCE
   ...

Each *CAPTIONL line causes the cursor to be positioned at the specified place
and the option number (indicated by !MENUOPTION) and the caption text to be
output.  The MENUOPTION variable is right-justified so menus with 10 or more
items will automatically line up if you use the same value for the column
number.  (Actually, since this field is three characters wide, menu items up to
999 will automatically line up, but that is far more than you are likely to
ever have on one screen).

DOING YOUR OWN SELECTION PROCESSING


Logon menus: Doing your own selection processing ``contents
Logon menus: Doing your own selection processing

Normally, once a menu is displayed, SECURITY prompts the user with "Enter
selection:".  If the user enters a number, the option specified by that number
will be executed; if the user enters "E", the menu will be exited; if the user
enters "R", the menu will be redisplayed, if the user enters "L", he will be
re-prompted for his passwords and, if he fails to enter them correctly, will be
logged off.

What if you want the menu processor to do something different? You might, for
instance, want to allow other strings (e.g.  the [F8] function key) to do an
exit; or, you might want to interpret pressing the [F1] as selecting option 1.


*ENTERSELECTION, logon menu keyword ``selection
*ENTERSELECTION, logon menu keyword
let you have complete control over the way the user is prompted for input
and over the way the input is processed.  Just like you can use the *START
command to define what is to be done when the menu is entered and the *FINISH
command to define what is to be done when the menu is exited, so you can use
the *ENTERSELECTION command to define how a user is to be prompted for his
selection.

For example, you might say

   ...
   *ENTERSELECTION
   SETVAR VEMENUSELECTION READSTRING ("Enter selection: ", "UPSHIFT")
   IF VEMENUSELECTION="QUIT" or VEMENUSELECTION="Q" THEN
     SETVAR VEMENUSELECTION "E"
   ENDIF

The SETVAR command sets the variable VEMENUSELECTION to the value of the
READSTRING function call.  The READSTRING function (documented in Appendix to
this manual) prompts the user for input and returns the data that he typed.

VEMENUSELECTION now contains the user's input; now, the IF statement checks to
see if it is "QUIT" or "Q".  If it is, then it sets VEMENUSELECTION to "E";
otherwise, VEMENUSELECTION remains what it was before -- the data that the user
typed.

When SECURITY finishes executing the *ENTERSELECTION commands, it looks at the
variable VEMENUSELECTION and executes it exactly as it would execute a normal
user response to SECURITY's own "Enter selection:" prompt.  If VEMENUSELECTION
contains "E", it will exit the menu; if it contains "R" (for Redisplay), it
will redisplay the menu; if it contains "L" (for Lockup), the user will be
re-prompted for his passwords (and logged off if he fails to enter them
correctly); if it contains a number, it will select that option of the menu.

Therefore, our example above simply implements QUIT and Q as inputs that exit
the menu (just like the "E" input normally does).

A more sophisticated example might be:

   *ENTERSELECTION
   SETVAR VEMENUSELECTION READSTRING ("Hit function key: ")
   IF VEMENUSELECTION=TERMFKEY(8) THEN
     SETVAR VEMENUSELECTION "E"
   ELSE
     IF TERMFKEYNUMBER(VEMENUSELECTION)<>0 THEN
       SETVAR VEMENUSELECTION STRWRITE(TERMFKEYNUMBER(VEMENUSELECTION))
     ENDIF
   ENDIF

In this case, we first compare the input value against the function
TERMFKEY(8).  TERMFKEY(N) is a predefined function that returns the
two-character escape sequence that HP terminals send when you hit function key
N (where N is a number from 1 to 8).  If the user's input was equal to
TERMFKEY(8), that means that he hit function key [F8], and we set
VEMENUSELECTION to "E".

If the user didn't hit [F8], we compare TERMFKEYNUMBER(VEMENUSELECTION) against
0.  TERMFKEYNUMBER(S) is the opposite of TERMFKEY(N) -- it returns the function
key number that must have been hit to transmit the text given by S or 0 if S
doesn't correspond to a function key escape sequence.

Thus, if TERMFKEYNUMBER(VEMENUSELECTION) is not equal to 0, the user must have
hit a function key; in this case, we set VEMENUSELECTION to
STRWRITE(TERMFKEYNUMBER(VEMENUSELECTION)) -- since STRWRITE translates a number
(in this case TERMFKEYNUMBER(VEMENUSELECTION)) into a string., VEMENUSELECTION
will now be set to the string representation of the number (1 through 7)
corresponding to the function key the user hit.  In other words, if the user
hit [F1], VEMENUSELECTION will be "1"; if the user hit [F5], VEMENUSELECTION
will be "5".

If neither IF statement is triggered, the user must have entered something
other than a function key -- in this case, VEMENUSELECTION keeps on having the
user's input.

Now, after the *ENTERSELECTION commands are done, SECURITY will look at
VEMENUSELECTION and execute it appropriately.  If the user hit [F8], SECURITY
will see an "E" and exit the menu; if the user hit, say, [F4], SECURITY will
see a "4" and execute menu option number 4.

These are only examples -- you can really do anything you like, as long as you
ultimately set the VEMENUSELECTION variable to the text that you want SECURITY
to execute ("E", "R" or the string representation of an option number).

You might, in fact, want to work out a general-purpose set of *ENTERSELECTION
commands and put them into a USE file that you can then execute from
*ENTERSELECTION blocks in all your menu files.

CONDITIONAL PROCESSING


Logon menus: conditional processing ``contents
Logon menus: conditional processing

Normally, every user of a particular menu has access to every caption in that
menu.  Suppose, however, you want to set up a single menu to be shared by a lot
of different users, but you only want certain users to have access to some of
the items in the menu.  You may want to do this (rather than just create a
separate menu for each user) because you have a lot of complex captions in
menu, and you don't want to have to maintain multiple copies of most of it.
One way might be to set up a caption like this:

   *CAPTION Run the month-end closing job
   IF HPUSER="CLERK" THEN
      ECHO Sorry, only the accounting manager is allowed to do this.
   ELSE
      RUN MONTHEND.PUB
   ENDIF

The user CLERK would be unable to execute the "month-end" item, but he would
still see it on his screen.

However, SECURITY has a better way: *IF/*ELSEIF/*ELSE/*ENDIF! Like the IF
command, *IF can evaluate any arbitrary expression.  *IF can be used to select
*CAPTIONs, *HEADERs, *STARTs, *FINISHes, *ENTERSELECTIONs -- any menu *keyword
you like.  This give you the power and flexibility to set up quite complex
menus that are shared by many users.

The syntax looks like this:


*IF, logon menu keyword
*ELSEIF, logon menu keyword
*ELSE, logon menu keyword
*ENDIF, logon menu keyword

   *IF expression THEN
   *keyword1
   [ commands for the above keyword ]
   [ *ELSEIF expression THEN        ]
   [ *keyword2                      ]
   [ commands for the above keyword ]
   [ *ELSE                          ]
   [ *keyword3                      ]
   [ commands for the above keyword ]
   *ENDIF

The example above could be replaced with:

   *IF HPUSER<>"CLERK" THEN
   *CAPTION Run the month-end closing
   RUN MONTHEND.PUB
   *ENDIF

Here's another example:

   *IF CAPABILITY("AM") THEN
   *HEADER Payroll menu (AM user - don't clear screen)
   *ELSE
   *HEADER TERMPOS(0,0)TERMCLEAR()Payroll menu
   *ENDIF

   *IF HPUSER="CLERK1" or CAPABILITY("AM") THEN
   *CAPTION Special task for CLERK1 and AM
      RUN CLERK1.PUB
   *ELSEIF HPUSER="CLERK2" THEN
   *CAPTION Special task for CLERK2
      RUN CLERK2.PUB
   *ELSEIF HPUSER[0:5]="CLERK" THEN
   *CAPTION Task for all other CLERKS
      RUN CLERK.PUB
   *ELSE
   *CAPTION Task for all non-CLERK, non-AM users
      RUN OTHER.PUB
   *ENDIF

ACCESSING USER PROFILE INFORMATION FROM WITHIN THE MENU


Logon menus: Accessing user profile information ``contents
Logon menus: Accessing user profile information
USERPROFILE.attrvar syntax, usable within menus

Sometimes you may want to access the user's SECURITY user profile information
(e.g.  the user's real name) from within your menu; you can do this by
specifying USERPROFILE.fieldname wherever you need this piece of information
(where the fieldname is one of the user profile fields available in the
LISTUSER selection conditions, see above).

For example, if you want to pass the user's real name as the ;INFO= string to a
program from within the menu, you can say:

   *CAPTION RUN MAIL SYSTEM
   RUN MYPROG.MAIL.SYS;INFO="USERPROFILE.NAME"

SECURITY will replace the USERPROFILE.NAME by the user's real name -- if this
happens to be JOHN SMITH, the command executed will be

   RUN MYPROG.MAIL.SYS;INFO="JOHN SMITH"

For more information on the fieldnames that are allowed, see the chapter on
Listing User Profiles, section "User Profile Attribute Variables and
Functions".

WITHCAPS: TEMPORARILY GRANTING EXTRA CAPABILITIES


WITHCAPS: temporarily granting extra capabilities ``contents
WITHCAPS: temporarily granting extra capabilities

Special note: although this feature is being described in the Logon Menus:
Advanced Features section of the SECURITY manual, it is also available within
STREAMX jobs (for ::commands) and in MPEX command files if you are a user of
both MPEX and SECURITY.

Often you might want to have users execute a menu, command file or job stream
that has more capabilities than they do.  For instance, you might want a menu
to access -- in a controlled way, of course -- a file that you normally
wouldn't let your users access; or, you may want to set up an MPEX command file
that lets users who lack SM capability build new accounts, provided that
certain checks are satisfied (e.g.  the new accounts don't have unusual
capabilities).

This is, of course, analogous to $NOPASS for STREAMX job streams, (see
"Allowing People To STREAM Certain Files Without Password Prompts") which lets
users stream jobs that log on as user IDs whose passwords the submitting users
don't know -- a user is thus allowed to perform a particular operation that
requires a given capability (for WITHCAPS) or logs on as a given user ID (for
$NOPASS) without in general having that capability or being able to use the
given user ID.  The command file, menu or job stream involved can then perform
the proper security checks to make sure that the high-capability operation that
it's trying to execute is actually legitimate.

The way the WITHCAPS mechanism works is rather simple:


WITHCAPS-PERMIT, STREAMX.DATA keyword ``permit
$WITHCAPS-PERMIT, STREAMX.DATA keyword
$WITHCAPS-FORBID, STREAMX.DATA keyword

  * You add lines to the STREAMX.DATA.VESOFT file that indicate which users
     can execute which command files/menus/job streams that get which
     capabilities.  For instance, saying

        $WITHCAPS-PERMIT  @.AP  APPFILE.CMD.SYS  "SM,AM"

     means that the file APPFILE.CMD.SYS can have a WITHCAPS command that
     grants it (temporarily, of course) SM and AM capability, but only when
     used by users in the AP account.  You can, of course, have multiple
     $WITHCAPS-PERMITs, but you can also restrict them by using
     $WITHCAPS-FORBIDs, e.g.

        $WITHCAPS-PERMIT  @.AP  @.CMD.SYS  "SM,AM"
        $WITHCAPS-FORBID  CLERK.AP  NEWUSER.CMD.SYS  "SM,AM"

     which lets all AP users use all CMD.SYS files that get SM and AM, but
     forbids CLERK.AP from using NEWUSER.CMD.SYS.

     Needless to say, it's very important that you've thought out all the
     security ramifications of letting these users use these files which
     temporarily get extra capabilities.  In particular, it is, of course,
     vital that the users not have write or save access to the mpefilesets
     specified in $WITHCAPS-PERMIT, since otherwise they'd be able to make up
     their own files with WITHCAPS commands in them.

   * Once the appropriate $WITHCAPS-PERMIT line has been added to the
     STREAMX.DATA.VESOFT file, the job stream, menu or command file would then
     include a

        ::WITHCAPS "caplist", cmd     in a STREAMX job
        WITHCAPS "caplist", cmd       in a SECURITY menu
                                         or an MPEX command file

     command, like

        WITHCAPS "SM", COPY F1,F2.PUB.ACCT;YES

     which will execute the given command while possessing the given
     capabilities (and will, of course, reset the capabilities to normal when
     done).  For example, a menu option using this might look like:

        *CAPTION ADD RECORD TO CONTROL FILE
        PROMPT STRING REC = "Enter record"; &
               CHECK = (REC[0:1]<>"A" and REC[0:1]<>"D"); &
               CHECKERROR = "Not allowed to add Add or Delete records"
        WITHCAPS "SM", CALC VEFWRITE ('CONTFILE,OLD;ACC=APPEND', REC)

     Similarly, MPEX command files (and UDCs) can use WITHCAPS, and STREAMX
     jobs can use ::WITHCAPS.  Note that the STREAMX ::WITHCAPS will change
     capabilities at job submission time (for the benefit of any :: commands
     that you might want to do), not at job execution time (since you can
     already determine the job execution capabilities by submitting the job
     under the right user ID).


WITHCAPS, security restrictions and other notes
need to keep a few things in mind when you use WITHCAPS:

   * First, be careful what you do when you've gotten capabilities with
     WITHCAPS.  For instance, don't just do an operation on a file whose name
     the user gave you (as a parameter or an input value) -- check to make sure
     that the user is really allowed to manipulate this file.  Don't just
     create a new user with the parameters that the user specified; check to
     make sure that, for instance, the capability list doesn't include SM, AM,
     OP or PM.

   * The WITHCAPS take effect only for the MPEX/LOGON/STREAMX process and for
     processes the command passed to WITHCAPS starts up.  Since we don't set
     the capabilities for the whole session (for security reasons), some
     operations (VEJOBINFO, for example) and programs might not recognize the
     temporarily acquired capabilities, though we believe that most (including,
     most importantly, the file system's file security checking) will.

   * Normally, when you run a program or execute a command file, MPEX (and MPE)
     first try to find a temporary file with that name and only look for a
     permanent file if the temporary file doesn't exist.  This would make it
     possible for a user to violate security by creating a temporary file with
     the same name as a command file or program that was to be executed while a
     WITHCAPS was in effect.  To avoid this, MPEX, LOGON and STREAMX will,
     while a WITHCAPS is in effect, only execute permanent command files and
     programs (unless you explicitly indicate otherwise in the command
     file/menu/job stream by using a file equation with a ,OLDTEMP on it).

   * By the same token, we do not execute UDCs when WITHCAPS is in effect.  The
     reason for this is that the operating system resolves UDCs by scanning the
     USER level UDCs first, then the ACCOUNT level and finally the SYSTEM
     level.  If we were to execute UDCs while a user had additional
     capabilities, all a user would have to do to circumvent security would be
     to set a USER level UDC with the same name as an ACCOUNT or SYSTEM level
     UDC or even an MPE command, so therefore we don't allow this.

   * Also for security reasons, MPEX will not honor MPEXCRITRESTRICTxxx
     variables (which restrict MPEX fileset handling commands to operate only
     on certain types of files) and VESOFTDEFAULTxxx variables (which set
     defaults for %ALTFILE, %COPY, %PRINT, :PREP, :RUN, :PREPRUN and implied
     RUN parameters).

   * You cannot use WITHCAPS to acquire PM, PH, MR, DS, IA and BA capabilities;
     fortunately, you probably wouldn't want to, since the most useful
     capabilities to acquire are SM, AM and OP, and possibly also AL and GL.

   * This feature is only available in MPEX if you are user of SECURITY.


The SECURCON.DATA.VESOFT file and its $ KEYWORDS``contents
The SECURCON.DATA.VESOFT file and its $ KEYWORDS

$ KEYWORDS: GENERAL GUIDELINES


keywords: general guidelines ``contents
$ keywords: general guidelines

The SECURCON.DATA.VESOFT is the heart of SECURITY's logon security facility.
It specifies which security options are to be set for which users.

As a rule, the file would look something like this:

   $keyword [parameter] [usersets]
   $keyword [parameter] [usersets]
   ...
   $keyword [parameter] [usersets]

For example:

   $VEPROFILE @.DEV @.PROD @.SYS-OPERATOR.SYS CAP=SM CAP=PM
   $TERM-DEACTIVATE 3 LDEV=20 LDEV=61 LDEV=62 MANAGER.SYS
   $MPE-OBSOL @.@-OPERATOR.SYS&CAP=IA
   $MPE-OBS-DAYS 45
   $MPE-OBS-DAYS 30 @.AP @.GL
   $MPE-OBS-DAYS 20 @.SYS
   $ALLOW REPLY,ABORTIO @.DEV JACK,@.@

As you see, each keyword (e.g.  $VEPROFILE, $TERM-DEACTIVATE, etc.) is followed
by (optionally) a parameter (such as 3, 45 or REPLY,ABORTIO) followed by zero
or more usersets.  The usersets specify for which users this keyword is
applicable.

The SECURCON file is essentially free-formatted.  You can split a keyword and
its parameters over multiple lines:

   $VEPROFILE
      @.DEV
        @.SYS-OPERATOR.SYS

or combine several keywords onto one line (although we do not recommend that
you do this):

   $MPE-OBS-DAYS 45 $MPE-WARN-DAYS 30 @.AP

or put multiple spaces wherever single spaces are allowed:

   $MPE-OBSOL       @.AP    @.GL  @.DEV

The two places where you can not put a space or a line break are in the middle
of a parameter and in the middle of a string -- for instance,

   $MPE - OBSOL   @.AP               is WRONG
   $MPE-OBSOL @.@ - @.SYS            is WRONG
   $MPE-OBSOL @.@-@.AP-@.DEV-
                @.PROD               is WRONG
   $FORBID "BETWEEN(CLOCK,8:45AM,
                    9:15AM)" ...     is WRONG


Continuing SECURCON.DATA.VESOFT lines with & ``continuation
Continuing SECURCON.DATA.VESOFT lines with &
if a single parameter doesn't fit on one line? Well, you can always split
a line anywhere you can put a space; however, what if the parameter is so long
that you have to split it in the middle? For instance, you might have a very
complicated userset with many -s or &s or a long $FORBID expression.

In this case, you can put an "&" at the end of the line to be continued.  There
must be NO spaces immediately before the "&", although there can be leading
spaces in the continuation line (they will be ignored).  For instance, you
might say:

   $MPE-OBSOL @.@-@.AP-@.DEV-@.GL-MGR.PROD-&
                JACK.AP-PETE.GL
   $FORBID "BETWEEN(CLOCK,8:45AM,9:15AM) AND&
            BETWEEN(HPLDEVIN,25,35)" "Error: Can't do this" @.DEV

SECURITY allows you to specify a number of $ keywords.  Some of them expect a
parameter (e.g.  $MPE-OBS-DAYS expects a number indicating the number of days
after which an MPE password will be obsoleted); others do not.  All of them
allow you to specify zero or more usersets indicating who these keywords apply
to; if you don't indicate any usersets, SECURITY assumes that you want the
keyword to apply to everybody.

You may specify a particular keyword more than once.  For instance,

   $MPE-U-OBS-DAYS 45 @.AP
   $MPE-U-OBS-DAYS 25 @.PROD

sets the MPE user password obsolescence period to 45 days for users in the AP
account and to 25 days for users in the PROD account.

What if more than one occurrence of a keyword can apply to a particular user?
For instance, what if you say

   $MPE-U-OBS-DAYS 45 @.AP
   $MPE-U-OBS-DAYS 25 CLERK.AP

-- what obsolescence period will CLERK.AP have? Well, in case of conflict,
SECURITY will apply that instance of the keyword that is specified LAST.  In
the case of CLERK.AP, which matches both usersets (@.AP and CLERK.AP), the last
one specified ($MPE-U-OBS-DAYS 25 CLERK.AP) will take precedence, and
CLERK.AP's MPE user password will be obsoleted after 25 days.

This can be quite useful for setting up system-wide defaults and exceptions.
For instance,

   $VE-DEACTIVATE 5
   $VE-DEACTIVATE 3 CAP=SM CAP=PM
   $VE-DEACTIVATE 2 MANAGER.SYS @.AP

specifies that:

   1) All SECURITY user profiles will be deactivated after 5 consecutive
      unsuccessful logon attempts;

   2) User profiles that apply to users who have SM or PM capability will be
      deactivated after 3 attempts;

   3) User profiles for MANAGER.SYS and all AP account users will be
      deactivated after 2 attempts.

A user JACK.DEV who has PM capability will match both #1 and #2 -- everybody
matches #1, and JACK.DEV matches #2 because of his PM capability.  Therefore,
he'll be deactivated after 3 consecutive unsuccessful logon attempts, since #2
takes precedence.  MANAGER.SYS, who matches both #1, #2 (he has SM), and #3
will be deactivated after 2 consecutive unsuccessful logon attempts.

If you want to turn a particular option OFF altogether, you can say:

   $keyword OFF

For instance, to turn logging of successful logons off, just say

   $LOG-LOGON OFF

Note that if you specify a keyword without any usersets, (or with the word "ON"
in place of a userset), e.g.

   $NO-CONCUR-SESS
   $MPE-OBS-DAYS 30
   $VEPROFILE ON

then this keyword applies to all users in the system (thus, in the above
example, concurrent sessions with the same logon ID are disallowed for
everyone, the MPE password obsolescence period is set to 30 days system-wide,
and all users are required to have SECURITY user profiles).

BRIEF CATALOG OF SECURCON.DATA.VESOFT $ KEYWORDS


Brief catalog of SECURCON.DATA.VESOFT keywords ``contents
Brief catalog of SECURCON.DATA.VESOFT keywords

The following is a listing of all the $ keywords available within the
SECURCON.DATA.VESOFT file.  Each keyword is documented in much more detail
earlier in this manual.

   (* SECURCON.DATA.VESOFT *)

   $SYS-NAME             set system name for network features
   $DEFINE-USERSET       set special usersets

   (* Logon Restrictions *)

   $FORBID               impose arbitrary logon restrictions

   $PASS                 impose special passwords (e.g.  terminal passwords)

   $VEPROFILE            enable SECURITY user profiles
   $VEPASS-TEMP-PROMPT   set prompt for temporary passwords
   $VEPASS-PROMPT        set prompt for SECURITY passwords
   $VEPASS-PROMPT-FILE   set prompt file for SECURITY passwords
   $VE-NUM-PROMPTS       number of SECURITY passwords to prompt for
   $VE-NUM-TRIES         number of tries per SECURITY password
   $VE-TIMEOUT           set time limit to enter SECURITY password
   $NO-VEPASS            turn off SECURITY passwords for particular logons

   $BATCH-VEPROFILE      enforce SECURITY user profiles in batch

   $TERM-NUM-TRIES       number of tries per terminal password
   $CANT-USE-TERMINAL    restrict certain users from certain terminals

   $MPE-U-NEED-PASS      don't allow logons to IDs without passwords
   $NO-CONCUR-SESS       only allow one logon at a time per sess,user.acct
   $SESS-EDIT            session names must match a particular pattern
   $NO-BATCH             don't allow batch access for particular logons
   $SUPER-PROTECT        turn off special lockout avoidance feature

   (* Logon Restrictions: Password Obsolescence *)

   $MPE-OBSOL            enable MPE password expiration
   $MPE-WARN-DAYS        number of warning days for all MPE passwords
   $MPE-OBS-DAYS         number of days for all MPE passwords to expire
   $MPE-A-WARN-DAYS      number of warning days for account passwords
   $MPE-A-OBS-DAYS       number of days for account passwords to expire
   $MPE-G-WARN-DAYS      number of warning days for group passwords
   $MPE-G-OBS-DAYS       number of days for group passwords to expire
   $MPE-U-WARN-DAYS      number of warning days for user passwords
   $MPE-U-OBS-DAYS       number of days for user passwords to expire
   $MPE-WARN-PASSCHG     allow user to change password during warn period
   $MPE-OBS-PASSCHG      allow user to change password after expiration

   $VE-WARN-DAYS         number of warning days for SECURITY passwords
   $VE-OBS-DAYS          number of days for SECURITY passwords to expire
   $VE-WARN-PASSCHG      allow SECURITY password changing during warning period
   $VE-OBS-PASSCHG       allow SECURITY password changing after expiration

   (* Logon Violation Processing *)

   $TERM-DEACTIVATE      deactivate terminal after invalid logon attempts
   $VE-DEACTIVATE        deactivate profile after invalid logon attempts

   $VIOLATION-EXECUTE    arbitrary processing after invalid logon attempts

   (* Successful Logon Options *)

   $ALLOW                :ALLOW certain console commands to certain users
   $MENU-FILE            specify menu for usersets
   $WELCOME-MESSAGE      specify welcome messages for usersets
   $LOGON-EXECUTE        execute arbitrary expression whenever user logs on

   (* Logging Options *)

   $LOG-GOD              log executions of GOD.PUB.VESOFT
                          (see the MPEX User Manual for details)
   $LOG-LOGON            log all logons for specified usersets
   $LOG-STREAM           log whenever users stream jobs through STREAMX

   (* Maintenance Options *)

   $CHECK-MPE-USER       verify existence of MPE user before adding profiles
   $MAINT-FORBID         restrict maintenance commands by userset
   $MAINT-PERMIT         enable maintenance commands by userset
   $NET-SEND             forward profile changes to other systems
   $VE-DIFF-PASS         prohibit duplicate SECURITY passwords for same user
   $VE-PASSHIST-DAYS     number of days before reusing old SECURITY password
   $VEPASS-FORBID        advanced SECURITY password editing
   $VEPASSCHG-VERIFY     user must enter old password before changing to new
   one

   $USER-FIELD           create user-defined-fields in profiles
   $USER-FIELD-FORBID    edit user-defined-fields in profiles

   $ALLOW-MPE-PASSCHG    allow users to change their own MPE user passwords
   $MPE-PASS-EDIT        edit MPE user passwords
   $MPE-PASS-FORBID      advanced MPE user password editing
   $MPE-PASSHIST-DAYS    number of days before user can reuse old MPE user
   password

   (* Miscellaneous Options *)

   $GOD-MOVABLE          allow GOD program to run outside of PUB.VESOFT
   $GOD-RESTRICT         specify who can run GOD program
   $LOCKUP-MPE-PASS      prompt for MPE passwords in terminal lockup
   $MENU-LOGOFF-LOCKUP   make LOGOFF use lockup inside VEMENUs
   $MENU-UDC             control use of UDCs in menus
   $NO-HOST-CHECK        don't check for host node name


Usersets ``contents`news
Usersets

MPEX and SECURITY let you use usersets as a means of indicating sets of MPE
logons.  Usersets let you select jobs/sessions in a number of ways, including:

   - by their MPE user ID;
   - by their account name;
   - by their session name;
   - by the group they log on to;
   - by the device on which they log on;
   - by their capabilities;
   - by whether they log on online (session) or as a job (in batch);
   - and various other job/session attributes.

You can use usersets to:

   * Specify in SECURCON.DATA.VESOFT for which logons a particular SECURITY
     option is to be turned on.

   * Specify which SECURITY user profiles a %SEC command is to operate on.

   * Specify jobs to be processed by MPEX's commands %ABORTJOB, %ALTJOB,
     %BREAKJOB, %REPEAT ...  %FORJOBS, %PAUSEJOB, %RESUMEJOB, %TELL,
     %WARN/WARNF, etc.  (see the MPEX User Manual) or counted by the JSCOUNT
     function (see Appendix).

A "simple userset" can be one of the following:


session,user.account,group -- userset ``usersets
session,user.account,group -- userset

  session,user.account,group
   session,user.account       (in any group)
   ,user.account,group        (blank session name)
   user.account,group         (any session name)
   user.account               (any session name in any group)


LDEV=; userset keyword

  LDEV=devnumber             (on the terminal given by devnumber)
   LDEV<>devnumber            (on any terminal except devnumber)
   LDEV<devnumber
   LDEV<=devnumber
   LDEV>devnumber
   LDEV>=devnumber
   LDEV=devclass              (in the given device class)
   LDEV<>devclass             (not in the given device class)


HPDTCPORTID=; userset keyword ``dtcportid`portid
HPDTCPORTID=; userset keyword

  HPDTCPORTID="pattern"   (on the given DTC port)


HOSTNODENAME=; userset keyword``rfa`vt`remote`access`news
HOSTNODENAME=; userset keyword

  HOSTNODENAME="pattern"  (from the given HOST)


ACCESSING=; userset keyword ``filename
ACCESSING=; userset keyword

  ACCESSING=filename         (is accessing the given file)


CAP=; userset keyword

  CAP=capcode                (has the given capability)
   CAP<>capcode               (doesn't have the given capability)


ONLINE; userset keyword

  ONLINE                     (logged on online, in a session)


BATCH; userset keyword

  BATCH                      (logged on in batch, in a job)


WAIT; userset keyword

  WAIT                       (job in the WAIT state)


SUSP; userset keyword

  SUSP                       (job in the SUSP state)


SCHED; userset keyword

  SCHED                      (job in the SCHED state)


INTRO; userset keyword

  INTRO                      (job in the INTRO state)


EXEC; userset keyword

  EXEC                       (job or session in the EXEC state)


#Jxxx; userset keyword ``jobnumber
#Jxxx; userset keyword

  #Jxxx                      (a given job number)


#Axxx; userset keyword ``jobnumber
#Axxx; userset keyword

  #Axxx                      (STREAMX-scheduled job number)


#Sxxx; userset keyword ``sessionnumber
#Sxxx; userset keyword

  #Sxxx                      (a given session number)


DAY=; userset keyword

  DAY=dayofweek              (today is the given day-of-week)
     same for <>, <, <=, >, >=


TIME=; userset keyword

  TIME<hh:mm                 (current time is less than hh:mm)
     same for =, <>, <=, >, >=

   (where session, user, account, and group can include any MPE wildcards like
    @, #, ? or the MPE/iX "[xxx]" wildcard construct, even on MPE/V).

Examples of simple usersets include:

   JACK.AP         someone logged on as JACK.AP
   JACK.@          someone logged on as user ID JACK in any account
   PETE,@.X@       someone logged on with session name PETE
                     in any account that starts with X
   @.SYS,PUB       someone logged into the PUB.SYS group
   LDEV=20         someone logged on to LDEV 20
   LDEV<>61        someone logged on to any terminal except LDEV 61
   LDEV=MODEM      someone logged on to any terminal with device class MODEM
   HPDTCPORTID="0800090045b5 0100 "
                   someone logged on to DTC 0800090045b5, card 1, port 0
   HOSTNODENAME="SNOOPY.HPLAN.OURCO"
                   someone coming from the remote host SNOOPY.HPLAN
                   (which, in this example, is another HP3000)
   HOSTNODENAME="GEORGE.PCLAN.OURCO"
                   someone coming from the remote host GEORGE.PCLAN
                   (which is a PC using VT services)
   HOSTNODENAME="@.PCLAN.@"
                   someone coming from any "host" in the "PCLAN" domain
                   (again, presumably a PC and not an HP3000)
   ACCESSING=CUSTDB.DATA.VESOFT
                   someone accessing the CUSTDB database
   CAP=SM          someone logged on to a user with SM cap
   CAP<>IA         someone logged on to a user without IA cap
   #S1             someone logged on as session #1
   DAY=WEDNESDAY   all users, if today is Wednesday
   TIME>9:00       all users, if it is after 9:00 AM

Not all of the above usersets make sense in all contexts.  For instance, if
you're doing a %SEC, you're operating on fixed SECURITY user profiles, not
existing jobs or sessions, so it makes no sense to try to specify LDEV=,
ONLINE, WAIT, #Jxxx, etc.  On the other hand, if you're specifying usersets in
SECURCON, LDEV= and ONLINE might make sense, but WAIT won't (because any job
that gets to SECURITY's logon processing will already be in the EXEC state).

DAY= and TIME= (or <>, <, >, <= or >=) only make sense in SECURCON.  They
simply refer to the current day and time, and can be used to set SECURITY
options differently depending on, say, whether the logon is happening on the
weekend or during off hours.  They don't make much sense in a %SEC or
job-handling context, in which the current day and time are known.

HPDTCPORTID is an MPE/iX system variable that contains your DTC port ID, in the
form

   "DTC-lan-address"+" "+DTC-card-number"+"card-port-number"+" "

As you can see in the example above, you may use "?", "@", and/or "#" wildcard
characters to match the HPDTCPORTID.

HOSTNODENAME is an IP address in the form "node.domain.organization".  Like the
HPDTCPORTID variable, this can be matched using the standard wildcard
characters "?", "@", and "#".

These two values are mutually exclusive -- if you are using VT services, then
your HPDTCPORTID will be blank and HOSTNODENAME will contain the name of your
"host" system.  Likewise, if you are using a terminal hard-wired to a DTC, then
your HPDTCPORTID will contain valid data and the HOSTNODENAME will be blank.
What isn't obvious is that if you are connected to an HP3000 via a hard-wired
port on a DTC and then issue a :DSLINE command to go to another HP3000, then on
the second HP3000, you will have a HOSTNODENAME (the name of the first HP3000),
and your HPDTCPORTID will be blank.

A "userset" is more sophisticated than a "simple userset".  A userset can be
one of

   * simpleuserseta+simpleusersetb (e.g.  "@.AP+@.GL"), which includes anybody
     who is in either userset (in the example, anybody who's either in the AP
     or GL account);

   * simpleuserseta-simpleusersetb (e.g.  "@.AP-JACK,@.@"), which includes
     anybody in userseta who is not in usersetb (in the example, anybody who's
     logged on to the AP account except if he's logged on with a session name
     of JACK);

   * simpleuserseta&simpleusersetb (e.g.  "@.AP&CAP=AM"), which includes only
     those people who match BOTH usersets (in the example, anybody who is in
     the AP account AND has AM capability).

You can actually, +, -, and & together more than one simple user set (see
"Order Of Evaluation", below):

   * "@.AP+@.GL+@.PROD" means "anybody who's logged on to the AP, GL, or PROD
     account";

   * "@.@-OPERATOR.SYS-JACK,@.@" means "everybody in the system except for
     OPERATOR.SYS and people logged on with session name JACK";

   * "@.DEV&CAP=PM&LDEV=61" means "anybody who's logged onto the DEV account
     and has PM capability and is using LDEV 61";

You must never embed a blank inside a userset (e.g.  "@.AP + @.GL" is illegal)
because blanks are used to delimit usersets from one another and from the
keywords.  When you specify several usersets separated by blanks (e.g.
"$MPE-OBS-DAYS 30 @.AP @.GL @.PROD") all those sets are "+"d together -- in
this case, $MPE-OBS-DAYS will be set to 30 for all users in the AP, GL and PROD
accounts.

ORDER OF EVALUATION


Usersets: order of evaluation ``contents
Usersets: order of evaluation

The "order of evaluation" of usersets is always left-to-right; the userset

   @.AP+@.GL-MANAGER.@&CAP=SM

is interpreted as

   ((@.AP+@.GL)-MANAGER.@)&CAP=SM

In other words, the -MANAGER.@ applies to both preceding usersets (@.AP+@.GL)
and the &CAP=SM applies to everything that comes before it
((@.AP+@.GL)-MANAGER.@).

You may change this order of evaluation using parentheses; for instance, in

   @.AP+(@.GL-MANAGER.@)&CAP=SM

the -MANAGER.@ applies only to @.GL, and in

   @.AP+@.GL-(MANAGER.@&CAP=SM)

the &CAP=SM applies only to the MANAGER.@.

Parentheses can be nested, e.g.

  @.AP+((@.GL-MANAGER.@)&CAP=SM)

USERSETS THAT REFER TO HOST LOGONs


Usersets that refer to host logons ``contents`ns
Usersets that refer to host logons

The userset

   @.AP

refers to all the users that log on into the AP account on the local system
(the one on which SECURITY is currently running).

On the other hand, the userset


HOST=; userset keyword ``ns`usersets
HOST=; userset keyword

   @.AP;HOST=ALPHA

refers to any session on the local system which was originated (via a :REMOTE
HELLO) by a session running in the AP account on the system called ALPHA.
Similarly,

   LDEV=20;HOST=@

means any session originated from a session running on LDEV #20 of any host
system (;HOST=@) and

   @.AP&CAP=SM;HOST=XYZZY

means any session logged on to the AP account on the local system (@.AP) that
was originated by an SM user running on system XYZZY (CAP=SM;HOST=XYZZY).  Note
that the ;HOST= keyword applies only to the most immediately preceding object,
not to the entire userset -- if you want it to apply to more than one object,
say either

   @.AP;HOST=@&CAP=SM;HOST=@

or

   (@.AP&CAP=SM);HOST=@

To put it another way, say that you log on to system H as

   RYAN,USER.PROD,PUB (which has OP and AM capabilities) on LDEV 30

and then try to !REMOTE HELLO to system L as

   OPER.PROD,SYSOP (which has AL and PM capabilities) on LDEV 66

In this case, you'd match the following usersets on system L:

   OPER.PROD,SYSOP
   LDEV=66
   CAP=AL
   RYAN,USER.PROD,PUB;HOST=H
   CAP=OP;HOST=H
   LDEV=30;HOST=H
   @.PROD;HOST=H
   OPER.@&@.PROD;HOST=H
   CAP=PM&CAP=OP;HOST=H

Note that for SECURITY on system L to properly handle the ;HOST=H keywords,

   * the SECURCON.DATA.VESOFT file on system H must have had a line that said

        $SYS-NAME "H"

   * and when RYAN,USER.PROD logged on to system H, he must have logged on
     using SECURITY.

For more information, see the Logon Security And Multi-CPU Sites chapter of
this manual.

USING THE HPSUSAN NUMBER TO REFER TO MPE/iX HOST LOGONs


Using the HPSUSAN number to refer to MPE/iX host logons``contents
Using the HPSUSAN number to refer to MPE/iX host logons


MPE/V and MPE/iX differences: ;HPSUSAN=
: the following feature is only supported for MPE/iX systems.  MPE/V
systems can, however, use this feature to identify logons from MPE/iX systems.

When using ";HOST=sysname", SECURITY looks at the $SYS-NAME from the remote
system's SECURCON.DATA file.  (";HOST=sysname" allows you to have different
SECURITY restrictions based on which host the remote user is logging on from.)
Normally, this is sufficient since only the system manager and/or the security
administrator on the remote system can modify the SECURCON.DATA file.


HPSUSAN=; userset keyword
, SECURITY also provides a way to specify the HPSUSAN of the remote
system (only MPE/iX systems have an HP System Unique Serially Assigned Number):

   userset;HPSUSAN=number

This might be useful, for instance, if you don't trust all of the users with SM
capability on other system(s) connected to your network not to change the
SECURCON.DATA file (so as to pretend to be on a different system).

For example, suppose you have the following in your SECURCON.DATA file:

   $NO-VEPASS
      !HPJOBNAME,!HPUSER.!HPACCOUNT;HOST=BATMAN

this means any users signing on from system BATMAN, to the same
"session,user.account" on this system, shouldn't be asked for SECURITY
passwords).  If you don't want MANAGER.SYS on system JOKER to have access to
your system without entering SECURITY passwords, you should change the above
to:

   $NO-VEPASS
      !HPJOBNAME,!HPUSER.!HPACCOUNT;HOST=BATMAN;HPSUSAN=46853

(assuming BATMAN's HPSUSAN number is 46853).  SECURITY will not recognize any
system whose HPSUSAN<>46853 as "BATMAN".

$DEFINE-USERSET


DEFINE-USERSET, SECURCON file keyword ``usersets`contents
$DEFINE-USERSET, SECURCON file keyword
you want to set several options for the same list of usersets -- for
instance, you may want to set $MPE-OBSOL, $VE-OBS-DAYS, and $VE-WARN-DAYS for
several different usersets.

To do this, instead of saying

   $MPE-OBSOL        @.AP @.GL @.PROD MANAGER.SYS CAP=SM
   $VE-OBS-DAYS  30  @.AP @.GL @.PROD MANAGER.SYS CAP=SM
   $VE-WARN-DAYS  7  @.AP @.GL @.PROD MANAGER.SYS CAP=SM

you can say

   $DEFINE-USERSET PRODUSERS @.AP @.GL @.PROD MANAGER.SYS CAP=SM
   $MPE-OBSOL        !PRODUSERS
   $VE-OBS-DAYS  30  !PRODUSERS
   $VE-WARN-DAYS  7  !PRODUSERS

The $DEFINE-USERSET command defines the special userset variable PRODUSERS to
be all five of the usersets that follow it -- then, when you refer to
!PRODUSERS in a later SECURCON.DATA.VESOFT line, it's as if you referred to
those five usersets.  This will save you typing, avoid errors, and decrease the
time it takes to parse the SECURCON.DATA.VESOFT file at logon and, perhaps most
important, improve the maintainability of the SECURCON file.


Introduction: Remote access security ``contents`news
Introduction: Remote access security

Introduction

Dial-in lines and remote access through networks can be a particularly great
threat to your system security.  People do not need physical access to your
site to access your machine; nobody will be watching over their shoulders or
noticing any attempted foul play.

Other terminals, such as consoles or terminals that are authorized to log on to
sensitive accounts (like payroll) might also need to be specially protected to
prevent unauthorized people from using them.

To address both these needs, SECURITY allows you to impose additional passwords
on specific TERMINALS (MODEMS) or if they originally logged on to a different
machine (NETWORK).


Terminal passwords ``contents
Terminal passwords
Dial-in security
Device passwords
Console security
Special passwords


PASS, SECURCON file keyword for terminal passwords``termpass
$PASS, SECURCON file keyword for terminal passwords
passwords are implemented by adding $PASS keywords to your
SECURCON.DATA.VESOFT file:

   $PASS "CONSPASS" "TERMINAL PASSWORD" LDEV=20
   $PASS "REBECCA"  "TERMINAL PASSWORD" LDEV=61
   $PASS "TOPSEC"   "TERMINAL PASSWORD" LDEV=72

Now, whenever anybody tries to log on to LDEV 20, LDEV 61 or LDEV 72, something
like this will happen:

   :HELLO JOE.SHMOE     << User logs on to LDEV 61 >>
   ...
   ENTER TERMINAL PASSWORD:    << User enters FOOBAR >>
   Error: Incorrect terminal password
   ENTER TERMINAL PASSWORD:    << User enters REBECCA >>
   Welcome!  You are now signed on.

The user is prompted for a terminal password (with echo off, of course); if he
doesn't enter the correct password, he'll be logged off.


TERMINAL passwords and VIRTUAL TERMINAL (VT) services``hostnodename
TERMINAL passwords and VIRTUAL TERMINAL (VT) services
a PC is connected to a LAN, and that LAN is connected to the HP3000, users
can use VT or Virtual Terminal services to log onto the HP3000.  In this case,
the system assigns the next available LDEV number from a "pool" of numbers
(actually, all non-reserved LDEV numbers up to the configured maximum LDEV
number).  In this case, it is impossible to guarantee the same LDEV number for
each physical terminal.

However, when PCs are configured into a LAN, each PC is given a unique "IP
Address", which is usually described as "node.domain.organization".  Generally,
the "organization" part is the name of the company.  The "domain" is either the
department, building, general location or perhaps even the name of the network,
such as "ACCOUNTING", "BLDG5", "CALIFORNIA" or "PCLAN".  Finally, the "node" is
usually the name of the user, such as "GEORGE".

Although the actual LDEV number may vary, you can use the HOSTNODENAME userset
to validate access from a particular machine as follows:

   $PASS
      "HAMMER"  "NETWORK PASSWORD"  HOSTNODENAME="GEORGE.PCLAN.@"


MPE/V and MPE/iX differences: terminal passwords
MPE/iX systems, users connected through a DTC might not have a particular
LDEV number permanently assigned to their port (what HP calls a "non-nailed DTC
port").  Like users on a PC network, you can still assign terminal passwords to
these ports -- you just use the "DTC port ID" instead of an LDEV number! For
example,

   $PASS
      "NAIL"  "TERMINAL PASSWORD"  HPDTCPORTID="0800090045b5 0100 "

Of course, terminal passwords may be used together with MPE passwords, SECURITY
passwords, and any of the other SECURITY features.  They work particularly well
with the "Terminal, Time-Of-Day, And Day-Of-Week Restrictions" and the
"Deactivating Terminals After Unsuccessful Logon Attempts" options documented
earlier in this manual.

Note that terminal passwords will be UPSHIFTED before being compared to what
the user typed in.


TERM-NUM-TRIES, SECURCON file keyword ``terminal
$TERM-NUM-TRIES, SECURCON file keyword
, SECURITY gives the user two chances to correctly enter his terminal
password before logging him off.  If you like, you can change this number by
adding

   $TERM-NUM-TRIES number [usersets]

to your SECURCON.DATA.VESOFT configuration file.

MULTIPLE TERMINAL PASSWORDS

The actual syntax of the $PASS keyword is:

   $PASS "pass1[/(userset1)] [,pass2[/(userset2)]...]"
         "password type"
         userset

Say that you have four people who are authorized to use your dial-in line; we
believe it is better not to have one password shared by all four, but a
different password for each (audit standards often -- quite correctly -- frown
upon shared passwords).

If you set up a single terminal password on a dial-in line, then only those
people will be able to use it (which is good); however, what if one of them
leaves the company? You would have to change the password and inform all the
other people -- a somewhat cumbersome task.

Instead, you should set up several passwords -- one for each authorized user:

   $PASS "REBECCA,FOOBAR3,SASHA,DIMANCHE"  "TERMINAL PASSWORD" LDEV=61

This way, you can issue one of these passwords to each user -- if he leaves the
company (or for whatever reason loses the right to dial in to your computer),
you can merely remove his password, and nobody else will be affected.

Did you notice in the syntax diagram above that each password can be followed
by "/(userset)"? By taking advantage of the power of VESOFT usersets
(documented in the "Usersets" section of this manual), you can restrict each
password so that only certain users are allowed to use that password at all.
For example, if you have the following lines in your SECURCON.DATA file:

$PASS "REBECCA/(@.DEV), FOOBAR3/(@.DEV), &
       SASHA/(JOE,CLERK.AP+BILL,CLERK.AP), &
       DIMANCHE/(@.@)"
      "TERMINAL PASSWORD" LDEV=61

anybody who logs on to LDEV 61 (a modem?) and specifies a terminal password of:

   * REBECCA   will only be allowed to log on into the DEV account;

   * FOOBAR3   will only be allowed to log on into the DEV account;

   * SASHA     will only be allowed to log on as JOE,CLERK.AP or
               BILL,CLERK.AP.

   * DIMANCHE  will be allowed to log on anywhere he pleases.

Another good thing about multiple terminal passwords is in the logging
facility.  Every log record pertaining to any logon on a password-protected
terminal will include the number of the $PASS password that was specified; the
first password in a single $PASS is #1, the second password in the same $PASS
is #2, etc.

For instance, say that one person logs on (as OLIVER.DEV) with a password of
REBECCA and somebody else logs on (as STANLEY.DEV) with a password of FOOBAR3.
Their log records will then look like:

    Type :  Date    Time  Dev Logon          Target user/
                                             Violation type
   Logon :29OCT88 10:07PM 61  OLIVER.DEV     OK LOGON, PASS#1
   Logon :29OCT88 12:22AM 61  STANLEY.DEV    OK LOGON, PASS#2

This way, by looking at the log file, you can easily see not just what user ID
was used to log on but who was actually logging on (based on the password that
he used).

Note that only the terminal password number (starting with 1) is logged, not
the password itself -- otherwise, somebody might see the terminal password on
some stray log file listing.

FORBIDDING CERTAIN USERS TO USE CERTAIN TERMINALS


CANT-USE-TERMINAL, SECURCON file keyword ``terminal`termpass
$CANT-USE-TERMINAL, SECURCON file keyword
can restrict access to a terminal without configuring any actual passwords.
If you say

   $CANT-USE-TERMINAL LDEV=61-@.DEV

then only users in the DEV account (@.DEV) will be allowed to log on to LDEV
61.

Note: For more information, please see "Setting Up Special Passwords: The $PASS
Keyword" in the Logon Security section of this manual.


Introduction: LOGON security and multi-CPU sites``contents`news
Introduction: LOGON security and multi-CPU sites

INTRODUCTION: HOW PEOPLE CONNECT TO HP3000s

Since computers continue to increase in power and capability while the price
decreases, it is becoming much more common to see multiple HP3000s or other
computer systems connected together or "networked".  With a "network" of
computers, users are able to log on to one computer and then connect to a
"remote" computer using special network commands.

Even the terminals that are used to connect to a system are getting in on the
act as it becomes much more cost effective to buy a personal computer with
terminal emulation software than it is to continue using an obsolete "dumb"
terminal.  While many of these PCs-as-terminals are still hard-wired to the
computer using the same serial connection that the dedicated terminals used to
use, more and more are being connected to the HP3000 using "the network".


VIRTUAL TERMINAL access to an HP3000``vt
VIRTUAL TERMINAL access to an HP3000
both of these cases, the HP3000 offers a network service known as "VIRTUAL
TERMINAL" or "VT" service.  With this type of connection, the original computer
or PC appears to be a terminal connected directly to the HP3000, just like a
hard-wired serial port, but the LDEV number is assigned at the time the user
logs on from a "pool" of available LDEV numbers.  This "pool" of numbers is, in
reality, any LDEV number up to the highest configurable LDEV number that has
not been explicitly defined during system configuration.  For instance, LDEV 1
is the system disk, LDEV 6 is usually configured as a printer, LDEV 7 as a TAPE
drive, LDEV 10 as the job-stream device, and LDEV 20 as the console.  With this
configuration, the first user to log onto the system from a VIRTUAL TERMINAL
will be assigned to LDEV 2, the next user to LDEV 3, then 4, 5, 8, 9, 11, and
so on.

With this in mind, here are some important concepts to help in understanding
this section:

  *  The HOST system is generally the system a user connects to first, be it a
     PC on a LAN or an HP3000 from a direct-connect terminal.

  *  The REMOTE system is the system that the user is logging onto and doing
     XEQ MAIN.PUB.VESOFT SECLOGON.

  *  In this section, we sometimes refer to a LOCAL system.  Although this is
     always the system that the user is actually using, this will either be the
     REMOTE or the HOST system, depending upon whether the user is GOING TO or
     COMING FROM another system.  In other words, the LOCAL system is the HOST
     if you are GOING TO a REMOTE system, but it is the REMOTE system if you
     are COMING FROM a HOST.

For the examples that follow, there are the four ways in which a user
"connects" to a REMOTE MPE system from any HOST system:

  *  From one HP3000 to another (:DSLINE MACHINEB / :REMOTE HELLO).
  *  From an HP9000 system (HP-UX) to an HP3000 (usually using vt3k or ftp).
  *  From a "foreign" system (DEC, IBM, VAX, other UNIX systems, etc.) to an
     HP3000.
  *  From a Personal Computer (PC) on a Local Area Network (LAN) acting as a
     hardwired terminal (using VT services).

When connecting TO an MPE system, only the first method listed above fully
supports the features listed below.  When the connection is from any of the
other systems listed, our software treats the connection nearly the same as if
the user were hard-wired to the MPE system.

The network features of our software helps you answer the question:

  "What if you have multiple HP systems and want to...

  ...  not prompt users for SECURITY passwords on system BETA if they logged on
       (via :REMOTE HELLO) from system ALPHA using the exact same user id?"
       Presumably, this user has already been prompted for their passwords on
       system ALPHA, system ALPHA is then considered a TRUSTED SYSTEM.

  ...  not do SECURITY password checking for sessions that are started using
       :REMOTE HELLO from within a particular JOB STREAM that is running on the
       host system?"

  ...  forbid particular combinations of HOST and REMOTE logon?" (e.g.  you
       don't want to let AP account users on system ALPHA to log on as anything
       but AP account users on system BETA)

  ...  configure any of the other SECURITY options depending not just on the
       user's LOCAL system logon, but also on his logon ID (if any) on the HOST
       system?"

  ...  automatically insert MPE passwords into :REMOTE HELLO commands entered
       in MPEX or in jobs submitted via STREAMX?"

  ...  instantly update all of your HP3000s when a user changes security
       password?"

Our software handles most of these by allowing you to include HOST system
information as part of a userset.  Additional features of our software allow
you to ignore particular "hosts" (such as PCs on a LAN or "foreign" UNIX
systems) as well as coordinate updating user profiles on your entire network.

As we've already mentioned before (in the Usersets chapter), VESOFT usersets
let you configure various options by logon ID (session/user/account/group), by
logon device, by capabilities or by the logon mode (batch vs.  online).

However, they also let you take into account these values on the HOST system
(the one from which the current session was started via a :REMOTE HELLO) as
well as on the local system (the destination of the :REMOTE HELLO).

WHAT IS A "TRUSTED SYSTEM"?


What is a "TRUSTED SYSTEM"?``contents`news
What is a "TRUSTED SYSTEM"?

In theory, a user of a computer network may be allowed to access any computer
within the system.  In practice, however, the user usually has physical access
to only one computer using a terminal directly connected to the system (either
hardwired or through a modem), and must use special commands to access other
computers "on the network".  In order to access the first system, the user will
need to supply a correct logon ID and password.  When that user needs to access
another computer in that network, the user would need to re-enter his ID and
password.  As you might guess, this can become quite tedious if the user needs
to access several computers during the day.

If, however, the FIRST computer has some way of notifying the SECOND computer
that the user logged on to the first system correctly, then the second system
can skip prompting the user for a password.  The first system is considered a
TRUSTED SYSTEM since the second system trusts the first system when it says the
user is valid.

HOW SECURITY IMPLEMENTS TRUSTED SYSTEM ACCESS


How SECURITY implements TRUSTED SYSTEM access``contents`news
How SECURITY implements TRUSTED SYSTEM access
HOST=; userset keyword with $VEPROFILE

By using the ;HOST= keyword on a userset, your SECURCON file can be configured
to allow particular users access to the system, without the need for profiles
or passwords, based upon information retrieved from host system.

For example, you might say (in your SECURCON.DATA.VESOFT file):

   $VEPROFILE @.@-MANAGER.SYS;HOST=ALPHA

This means that SECURITY user profiles ($VEPROFILE) will be enforced for
everybody (@.@) except for sessions that originated from system ALPHA (the
host) where they are logged on as MANAGER.SYS.

Thus, if a user logs on as MANAGER.SYS on system ALPHA and then :REMOTE HELLOs
to the machine with the above SECURCON file, he will not be prompted for
SECURITY or terminal passwords; he will not be denied access based upon any
terminal, time-of-day or day-of-week restrictions; and finally, no logon MENU
will be invoked.

It is important to realize that the ;HOST= parameter qualifies the object
immediately preceding it.  In this example, MANAGER.SYS;HOST=ALPHA indicates
that we're talking about a MANAGER.SYS logon on system ALPHA, not about a
MANAGER.SYS logon from a directly connected terminal.

Similarly,

   $MPE-OBSOL @.@-BATCH;HOST=?@

means "enforce MPE password obsolescence for all users except for those that
are logged on from jobs (BATCH) running on any host (;HOST=?@)";

Parenthesis are used to group multiple usersets for which the ;HOST= parameter
applies, e.g.:


NO-VEPASS, SECURCON file keyword (example)
$NO-VEPASS, SECURCON file keyword (example)

   $NO-VEPASS OPER.PROD&(LDEV=20+CAP=OP);HOST=XYZZY

disables SECURITY password prompting for a user who:

  - logs on as OPER.PROD (on the LOCAL system) from anyone who originally
    logged on to HOST system XYZZY's console (LDEV 20)

  - logs on as OPER.PROD (on the LOCAL system) from anyone who has OP
    capability on HOST system XYZZY.

Without the parenthesis, i.e.

   $NO-VEPASS OPER.PROD&LDEV=20+CAP=OP;HOST=XYZZY

disables SECURITY password prompting for a user who:

  - logs on as OPER.PROD (on the LOCAL system) using the LOCAL system's console
    (LDEV 20).

  - logs on ANYWHERE on the LOCAL system from anyone who has OP capability on
    HOST system XYZZY.

As you can see, this is VERY different from what you might expect and could
lead to security breaches if you are not careful.

The most common method of defining a "trusted" logon is as follows:

   $NO-VEPASS !HPJOBNAME,!HPUSER.!HPACCOUNT,!HPGROUP;HOST=?@

SECURITY on the LOCAL system first replaces "!HPJOBNAME" with the local user's
job/session name, "!HPUSER" by the local user's user name, "!HPACCOUNT" by the
account name, and "!HPGROUP" by the group name; then, it checks to see if that
is indeed the logon used by the host session (on ;HOST=?@, which means whatever
host it came from).  Thus, any session that logs on the same way as it did on
the HOST will not be prompted for SECURITY passwords on the LOCAL system.

Note that, of course, this will work only if all of your systems are properly
secured -- if you use the above $NO-VEPASS line and any of your systems is
unsecured, people can use that system to break into the others.  In fact, if
you're not confident that all your systems are secured, we recommend that you
do not use the ;HOST= syntax on the $NO-VEPASS keyword or when "excluding"
usersets from $VEPROFILE.

A quick review:

   * As we said before, ;HOST= applies only to the immediately preceding object
     within a userset; thus:

        @.@-MANAGER.SYS;HOST=ALPHA

     means everybody (@.@) on the LOCAL system EXCEPT for someone from HOST
     system ALPHA who has logged on as MANAGER.SYS.

        (@.@-MANAGER.SYS);HOST=ALPHA

     means everybody from HOST system ALPHA EXCEPT for MANAGER.SYS on system
     ALPHA.  However, this does NOT apply to anyone who has logged on to the
     LOCAL system directly (i.e.  from a hard-wired terminal).

   * The "HOST computer" refers to the computer upon which the :REMOTE HELLO
     command was entered.

   * The "LOCAL computer" is the one on which the SECURITY logon is currently
     taking place.  (the destination of the :REMOTE HELLO)

     For example, if you :HELLO onto ALPHA, :REMOTE HELLO from ALPHA to BETA,
     :REMOTE HELLO from BETA to GAMMA, and :REMOTE HELLO from GAMMA to DELTA,
     then:

       - the host computer for the DELTA logon is GAMMA,

       - the host computer for the GAMMA logon is BETA,

       - the host computer for the BETA logon is ALPHA,

       - and there is no host for ALPHA.

CONFIGURING MULTIPLE CPUs FOR TRUSTED SYSTEM ACCESS


Configuring multiple CPUs for trusted system access``contents`news
Configuring multiple CPUs for trusted system access

Before you can use the ;HOST= syntax on any LOCAL system, two things must have
happened on the HOST system:


SYS-NAME, SECURCON file keyword ``system`name
$SYS-NAME, SECURCON file keyword

  * The SECURCON.DATA.VESOFT file on the HOST system must include a line that
     says

       $SYS-NAME "systemname"

     this identifies the HOST system to the LOCAL system.  The only way that
     SECURITY knows from which HOST the logon takes place is by looking at the
     $SYS-NAME keyword in the HOST's SECURCON.DATA.VESOFT file.  Thus, if the
     HOST system's SECURCON says:

        $SYS-NAME "SNOOPY"

     then the LOCAL system's SECURCON can say:

        $NO-VEPASS MANAGER.SYS;HOST=SNOOPY

     to allow SECURITY-passwordless logons from a user logged on as MANAGER.SYS
     on SNOOPY.

   * The user must have been validated on the HOST system using our SECURITY
     program.  Our program will then store some information about the user on
     the HOST system in a place where it can be accessed later by our program
     on the LOCAL system.

Unless both of these things are done on the HOST system, any ;HOST= keywords on
the LOCAL system will not work.

$NO-HOST-CHECK FOR NON-HP3000 SYSTEMS and VIRTUAL TERMINAL services


NO-HOST-CHECK, SECURCON file keyword
$NO-HOST-CHECK, SECURCON file keyword
$NO-HOST-CHECK for non-HP3000 host systems
Testing for VIRTUAL TERMINALS (VT) using $NO-HOST-CHECK

Since one of the requirements for our software to detect remote logons is that
our SECURITY logon program has to have been run on the HOST system, it should
be fairly obvious that we cannot check your logon if the "host" is not an
HP3000.  Most of the time, this isn't a problem, since it is very likely that
you would want to check passwords when a user is coming from, say, a UNIX
system where "users" and "accounts" don't have the same meaning.


REMOTE FILE ACCESS (RFA) during LOGON processing
was noted above, when you log onto the "host" system, our software stores
information about the user on the HOST system in a place where the LOCAL system
can access it during logon.  Our program accesses this information using a
network facility known as "Remote File Access" or RFA.  Some non-HP3000 systems
that can be connected to the same network as your HP3000 do not support RFA.
Normally, this is not a problem since if SECURITY is unable to obtain RFA
access, it treats the logon as if it were through a directly-connected
terminal.  You don't get the benefits of ";HOST=", but it doesn't hurt anything
either.

However, some networks are especially ill-behaved.  Not only do they not
support RFA, they completely ignore any network requests for this service
(instead of returning an error).  The network simply waits (by default, on most
systems, five minutes!) until the request times out, then returns an error to
SECURITY.  This problem is most often encountered on networks that use PCs as
terminals "on the LAN".

To avoid this problem with the nodes that don't support RFA, but still let you
take advantage of ";HOST=" for the nodes that do, SECURITY provides the keyword
"$NO-HOST-CHECK".  The syntax is simple:

   $NO-HOST-CHECK nodenamepattern

for example,

   $NO-HOST-CHECK @.PCLAN.VESOFT
   $NO-HOST-CHECK PC@

Notice that the "nodenamepattern" can have an "@" in any part of the nodename
(which is similar to a file, i.e.  "nodename[.domain[.organization]]").

You may have as many "$NO-HOST-CHECK" entries in the SECURCON.DATA.VESOFT file
as you like; however, they must be before the first ";HOST=".

OTHER RELATED FEATURES OF ;HOST= SYNTAX

In addition to allowing you to define a "trusted" logon, the ;HOST= keyword can
be applied to other SECURCON keywords for different effects.  For example:

   To only allow JOBs (but not SESSIONs) on the host to log on to the LOCAL
   system without prompting, use something similar to this:

      $NO-VEPASS (!HPJOBNAME,!HPUSER.!HPACCOUNT&BATCH);HOST=ALPHA

   To DISALLOW "PAYROLL" users from system XYZ from logging on in the "ACCOUNTS
   RECEIVABLE" account, you could use this example:

      $FORBID "TRUE" "Access DENIED" @.ACCTRECV&(@.PAYROLL);HOST=XYZ

   (Although the parenthesis around "@.payroll" aren't strictly necessary for
   this example, you should get in the habit of adding them before any ;HOST=
   keyword to remind you exactly which "userset" is being defined as "on host
   XYZ").

MAINTAINING SECURITY USER PROFILES ON MULTIPLE SYSTEMS


Maintaining SECURITY user profiles on multiple systems ``contents
Maintaining SECURITY user profiles on multiple systems
Multi-CPU user profile maintenance

If you have two or more HP3000s, you might want to make sure that your SECURITY
user profiles are 'in sync' on all (or some) of them; for instance,

   * if a new profile is added on one computer, you might want it automatically
     added on the other computers;

   * if a SECURITY password is changed on one computer (either voluntarily or
     because it is obsolete), you might want it automatically updated on the
     other computers;

   * if a user profile is deleted from one computer, you might want it
     automatically deleted from the other computers.

SECURITY can take care of all this for you.

Let's consider a simple example: let's say that you have two machines, ALPHA
and BETA, whose nodenames are NODEA and NODEB.  (Although we recommend keeping
the NODE name the same as the $SYS-NAME, this example will use different names
in order to be complete.) You want to have all the additions, changes, and
deletions on ALPHA (NODEA) automatically reflected on BETA (NODEB).  What
should you do?

   1. You must tell SECURITY on system ALPHA that you want to send all the
      SECURITY user profile change information to system BETA.

   2. You must tell SECURITY on system BETA that you want to receive the
      information from system ALPHA.

   3. You must tell SECURITY on system BETA exactly which changes from ALPHA
      you want reflected on BETA.

   4. You must start the NETRECV task executing under the BACKG job on system
      BETA, to receive update notifications from ALPHA and implement them on
      BETA.

      NOTE: in it's simplest configuration, SECURITY actually passes
      information from one system to another by pulling the data from the
      original machine to the machine where changes will take place.

NOTE: In order for BACKG to work properly, our SECURITY must be run through our
      LOGONUDC.  It is preferable to have this UDC set at the system level, but
      if you do not secure your entire system, this may be set at the ACCOUNT
      level for the VESOFT account.  (please see %BACKG in the MPEX Commands
      chapter of the MPEX User Manual for details)


NET-SEND, SECURCON file keyword ``ns
$NET-SEND, SECURCON file keyword
, configure system ALPHA to send profile information to BETA.  You would
do this by adding the following lines to your SECURCON.DATA.VESOFT file:

   $SYS-NAME "ALPHA"
   $NET-SEND BETA

Note that the $SYS-NAME keyword indicates the name of the LOCAL system (in this
case, ALPHA), and the $NET-SEND line(s) indicated the name(s) of the REMOTE
system(s) that will receive profile updates (in this case, only system BETA
will be receiving changes).  These "system names" need not be your actual node
names or DSLINE device names (although this might be convenient if you can
manage it) -- rather, they are the names which SECURITY uses to identify your
machines.


FROM-SYS, NETRECV configuration keyword ``ns
$FROM-SYS, NETRECV configuration keyword
, configure system BETA to pull (receive) profile change information from
system ALPHA.  You will need to build a file called NETRECV.DATA.VESOFT on
system BETA.  For our example, the file contains the following line:

   $FROM-SYS NODEA ALPHA

This means: "pull (receive) SECURITY user profile information from the system
called ALPHA using the node name (or DS/3000 device name) NODEA to log on to
the remote system".

While you're doing this, you should also make sure that your
SECURCON.DATA.VESOFT file on the receiving system (in this example, system
BETA) contains an appropriate $SYS-NAME line, e.g.

   $SYS-NAME "BETA"


NETRECV.VESOFT group, remote security maintenance
, after building the NETRECV.DATA.VESOFT file shown above, you should
build one more file on system BETA -- this one should be called
ALPHA.NETRECV.VESOFT, and it will tell SECURITY exactly what it should do with
the user profile information it gets from system ALPHA.

Again, referring to the example we are building, we want to maintain exactly
identical profiles, so we need to set up the ALPHA.NETRECV.VESOFT file as
follows:

   $RECEIVE @ !HPJOBNAME,!HPUSER.!HPACCOUNT @.@

Note that you can specify more than one remote userset for a $RECEIVE keyword,
the general format of which is:


RECEIVE, sysname.NETRECV.VESOFT keyword ``ns
$RECEIVE, sysname.NETRECV.VESOFT keyword

     $RECEIVE operations localuserset remoteuserset [remoteusersets]

Here are some examples and their explanation:

   $RECEIVE CHANGE      !HPJOBNAME,!HPUSER.GL          @.AP
   $RECEIVE ADD,CHANGE  !HPJOBNAME,!HPUSER.!HPACCOUNT  @.@-@.AP
   $RECEIVE DELETE      !HPJOBNAME,!HPUSER.!HPACCOUNT  @.TEST @.DEV

   * Any CHANGEs to any AP account user on system ALPHA are to be reflected on
     system BETA as changes to a user with the same job/session name and user
     name but in the GL account.  The important point here is that the third
     parameter indicates which remote user IDs are to be monitored, while the
     second shows which user IDs on the local system they correspond to.  In
     this case, you would need the same MPE accounting structure on system BETA
     in the GL account as you do on system ALPHA in the AP account.

   * Any ADDitions or CHANGEs to any user on system ALPHA except for those in
     the AP account (@.@-@.AP) are to be reflected on system BETA as additions
     or changes to the same user ID.  The "!HPJOBNAME,!HPUSER.!HPACCOUNT"
     merely tells SECURITY to keep the same user ID.

   * Any DELETEs of users in the TEST or DEV accounts on system ALPHA are to be
     reflected on system BETA.

     In this case, additions of new users to the AP account on system ALPHA are
     not automatically reflected on system BETA; similarly, deletions of users
     on system ALPHA are not automatically reflected on system BETA except in
     the DEV and TEST accounts.  This is intentional -- often you want to
     maintain somewhat different configurations on two systems, with some users
     existing on one but not on the other.

A few details (which you might have already guessed) about the $RECEIVE syntax:

   * The "operation" parameter can be one of "ADD","CHANGE","DELETE", any
     combination of the three separated by commas or "@".

   * The "localuserset" parameter can contain either an explicit job session
     name, user name or account name (e.g.  "GL" in the first line) or
     "!HPJOBNAME", "!HPUSER" or "!HPACCOUNT", indicating the remote job name,
     remote user name or remote account name, respectively.  If you want to
     indicate that the job name, user name or account name are to be preserved,
     use the "!HPxxx" syntax, not an "@".

   * The "remoteuserset" parameters can be arbitrary VESOFT usersets (with
     '+'s, '-'s or '&'s); however, it doesn't make sense for you to use group
     names or the CAP=, LDEV=, BATCH or ONLINE keywords in this context.

Now, for the last step -- you must start the NETRECV task running under the
BACKG job on system BETA.  If you have MPEX, you can issue the following BACKG
commands directly at the "%" prompt.  If not, run the MAIN program with the
",SEC" entry point as follows:

   :RUN MAIN.PUB.VESOFT,SEC
   SECURITY/3000 27Nymmdd (c) VESOFT Inc, 1981 05:225 For help type 'HELP'

   %SEC BACKG STARTJOB        (* If it's not already running *)
   %SEC BACKG START,NETRECV
   %SEC EXIT

(When MAIN is run with the ,SEC entry point it will automatically prompt with
"%SEC")

This task will run in background, waiting for system ALPHA to tell it about any
SECURITY user profile changes; whenever it gets such a message from system
ALPHA, it will immediately update the database.

NETRECV will log on to ALPHA as BETA,NETSEND.VESOFT,NETSEND.  This is a special
user which does not require a profile as it is used exclusively by our program.
In effect, the following "$FORBID" logic is applied to this logon:


HOST=; userset keyword with $FORBID ``ns`usersets
HOST=; userset keyword with $FORBID

   $FORBID "TRUE"
      "NETSEND.VESOFT only usable for internal SECURITY/3000 purposes"
     @,NETSEND.VESOFT-BACKG,MANAGER.VESOFT;HOST=@

This means that all logons to NETSEND.VESOFT will be forbidden unless they come
from a remote user that is logged on as BACKG,MANAGER.VESOFT.  It will thus
allow the NETRECV task running under the BACKG job to log on to NETSEND.VESOFT
but forbid everybody else.

Now that all of this has been explained, you will probably want to duplicate
everything that was added to system A on B and everything added to B on A (with
appropriate internal changes, of course).  This will automatically update in
both directions, so a change made on either system will be instantly reflected
on the other system.

What if an update starts out on system ALPHA and then eventually gets back to
system ALPHA? Say that all your "localuserset" parameters on your $RECEIVEs are
"!HPJOBNAME,!HPUSER.!HPACCOUNT", so your update of JACK,MGR.AP on system ALPHA
causes an update of JACK,MGR.AP on BETA, which in turn sends a message back to
ALPHA telling it to update the profile on ALPHA.  To avoid such infinite loops,
SECURITY keeps track of all the user IDs and system names that have been
updated as a result of a single update; when an attempt is made to update a
user twice, SECURITY detects the loop and stops the "automatic forwarding".

WHAT IF YOU HAVE MORE THAN TWO COMPUTERS?


What if you have more than two computers ``contents
What if you have more than two computers

The multi-cpu system described above can be represented by the following
picture:

    +-----------+              +----------+
    |   ALPHA   |<<---------->>|   BETA   |
    +-----------+              +----------+
        NODEA                      NODEB

However, what do you do when you add a third machine? (or a fourth, fifth,
sixth, etc...?)

No problem!

The two-machine configuration described above is actually a minimal version of
a "ring" topology, where changes are passed from the first machine to the
second, the second machine to the third, and so on until the LAST machine in
the chain transmits data to the FIRST machine.

For example, let's rename system "BETA" to system "OMEGA" and add the new
system "EPSILON" to the chain.  Using a ring analogy, the network now looks
like this:

    +---------+      +---------+      +---------+
+->>|  ALPHA  |---->>| EPSILON |---->>|  OMEGA  |---+
|   +---------+      +---------+      +---------+   |
|      NODEA            NODEE            NODEZ      |
+---------------------------------------------------+

As you can see, you can put as many of "nodes" between ALPHA and OMEGA as you
want.  In actual practice, however, you are not likely to add more than a dozen
nodes in this manner.  After that point, it may be easier to define a star or
wheel type of network in which one machine is considered the "hub" and all
other machines are "spokes".  Changes made on any spoke are only sent to the
hub, and the hub is then responsible for forwarding the changes to the other
spokes.

The reason that this works is due to the fact that you can specify more than
one $NET-SEND in your SECURCON.DATA.VESOFT file to indicate that user profile
change information should be transmitted to several computers.  For example:

   $SYS-NAME "HUB"
   $NET-SEND ALPHA
   $NET-SEND EPSILON
   $NET-SEND OMEGA

Similarly, you can specify more than one $FROM-SYS in your HUB's
NETRECV.DATA.VESOFT file, indicating that information should be received from
several computers.

   $FROM-SYS  NODEA  ALPHA
   $FROM-SYS  NODEE  EPSILON
   $FROM-SYS  NODEZ  OMEGA

If you have many machines, you might want to set up a pair of files in the
group NETRECV.VESOFT that contains a list of machine names and DSLINE node
names.  You can then refer to these lists of machines in $NET-SEND and
$FROM-SYS keywords.  For example, you might build a file called
SPOKENS.NETRECV.VESOFT (for SPOKE NameS) that contains the lines:

   ALPHA
   EPSILON
   OMEGA

and then say in your SECURCON file

   $NET-SEND ^SPOKENS.NETRECV.VESOFT

Then build SPOKEDS.NETRECV.VESOFT (SPOKE DSlines) which contains:

   NODEA
   NODEE
   NODEZ

and in your NETRECV.DATA.VESOFT file

   $FROM-SYS ^SPOKEDS CHANGES

The file CHANGES.NETRECV (on the HUB) would be used for ALL the nodes listed in
SPOKEDS.  Each "spoke" machine (ALPHA, EPSILON and OMEGA) should have $NET-SEND
HUB in their SECURCON file and $FROM-SYS HUB in their NETRECV file.  Therefore,
a change on system ALPHA will be sent to the HUB system which in turn will be
received from the HUB by EPSILON and OMEGA.

Note that if your system names are the same as their DSLINE node names, then
the same file can be used for both the SECURCON $NET-SEND and NETRECV $FROM-SYS
keywords.

WHICH PARTS OF A USER PROFILE GET TRANSMITTED?


Which parts of a user profile get transmitted? ``contents
Which parts of a user profile get transmitted?

When a user is changed, it usually wouldn't make sense to transmit the entire
user profile, including the terminal restrictions, time-of-day restrictions,
day-of-week restrictions, and menu file.  This is because these things are
typically quite different on different systems -- you'd almost certainly want
to have different menu files on different systems, the terminals are configured
as different LDEVs, and the normal working days and times might be different
too.

Therefore, only the user name and password information (including password
history, last change date, etc.) actually get sent from one system to another.
What if you want to impose terminal, time-of-day or day-of-week restrictions on
users who might get, say, automatically added as a result of an addition on
another system? We suggest that you do this using the $FORBID keyword, which
lets you impose such restrictions on entire usersets, not just individual user
profiles; thus, you can say (in your SECURCON file):

   $FORBID "NOT BETWEEN(CLOCK,9AM,5PM)" "Bad time" @.AP

which will impose a time-of-day restriction on all the users in the AP account
-- these restrictions will be enforced even though the users won't have
specific time-of-day restrictions in their user profiles.

What about menu files? The $MENU-FILE keyword lets you impose them on a
userset, too:

   $MENU-FILE  MYFILE.DATA.AP  @.AP-MGR.AP

will configure MYFILE.DATA.AP as the menu file for the entire AP account
(except for MGR.AP) even if no menu file is set up in each AP account user's
profile.

What about user-defined fields (fields created by the $USER-FIELD keyword,
documented earlier)?  Well, if you would also like user-defined fields to be
forwarded whenever you change a profile (they are, of course, automatically
included with an ADD), simply change the $RECEIVE command (in the
"nodename.NETRECV.VESOFT" file) to include the option "CHANGE=(VEPASS,UF)".
For example:


CHANGE=(...), $RECEIVE option to send profile items``UF`VEPASS
CHANGE=(...), $RECEIVE option to send profile items

   $RECEIVE  ADD,CHANGE=(VEPASS,UF)  !HPJOBNAME,!HPUSER.!HPACCOUNT @.@

Profile items that can be included in this list are: VEPASS, UF (UserFields),
DAYS, TIME, TERMINALS and MENU.  Note that VEPASS refers to SECURITY passwords,
not MPE passwords.  Important: if you use a list, VEPASSwords are not sent
unless you specify them (e.g.  CHANGE=(UF) will only modify user-defined
fields).

PUSHING: ANOTHER METHOD OF MAINTAINING SECURITY PROFILES ON MULTIPLE SYSTEMS


Pushing: another method of maintaining SECURITY profiles ``contents
Pushing: another method of maintaining SECURITY profiles
Multi-CPU user profile maintenance via "pushing"

Normally, a SECURITY user profile on system ALPHA gets moved to system BETA by
a NETRECV task running under the BACKG job on BETA which keeps a remote session
logged on to ALPHA.  What if, however, you don't want to keep this session
permanently logged on?

SECURITY lets you indicate that data is to be "pushed" across the network --
i.e.  have the data transfer be done by the computer on which the changes were
initially done -- rather than "pulled".

(In the following discussion, "system ALPHA" is the system on which the
SECURITY user profiles were changed; "system BETA" is the system you wish to
forward those changes to.)


FROM-SYS-PUSHED, NETRECV configuration keyword ``ns
$FROM-SYS-PUSHED, NETRECV configuration keyword

) Instead of having a "$FROM-SYS nodename sysname" line in your
   NETRECV.DATA.VESOFT file on system BETA, you should have a "$FROM-SYS-PUSHED
   nodename sysname" line.  This tells the NETRECV task on BETA that the data
   from ALPHA will be pushed by ALPHA, and doesn't need to be pulled by BETA.


PUSH-IMMEDIATE, NETRECV configuration keyword ``ns
$PUSH-IMMEDIATE, NETRECV configuration keyword

) There are two different ways that you can have system ALPHA push data to
   system BETA -- immediately or intermittently.

   a) If you add to your NETRECV.DATA.VESOFT file on system ALPHA a line that
      says "$PUSH-IMMEDIATE BETA", the NETRECV task on ALPHA will -- every time
      a change is made on ALPHA -- do a :REMOTE HELLO to BETA, transmit the
      change, and do a :REMOTE BYE.


PUSH-INTERMITTENT, NETRECV configuration keyword ``ns
$PUSH-INTERMITTENT, NETRECV configuration keyword

  b) If you add a line that says "$PUSH-INTERMITTENT BETA", the changes will
      only be pushed when you do a %SEC NETPUSH command (either online or using
      the NETPUSH task under the BACKG job).  BACKG allows you to schedule the
      NETPUSH task to run once a day at a given time (1:00 AM, by default) so
      that it transmits all the changes to all the systems specified in the
      $PUSH-INTERMITTENT commands.  If you find that you want to send the data
      to the other machines immediately, you can just do a %SEC NETPUSH online.


NETPUSH, %SEC command for multi-cpu maint. (push) ``ns
NETPUSH, %SEC command for multi-cpu maint. (push)

  Please notice that you must still keep the NETRECV task running on system
   BETA; the main difference is it never logs onto system ALPHA.  In addition,
   you must either run the NETRECV task on system ALPHA (for $PUSH-IMMEDIATE)
   or the NETPUSH task (for $PUSH-INTERMITTENT) to transmit the data to system
   BETA.  [A third alternative is to manually issue a %SEC NETPUSH command
   which is what the NETPUSH task does once a day.] The NETRECV task on system
   BETA then updates the SECURITY user profile.

MULTI-CPU USER PROFILE MAINTENANCE EXAMPLES


Multi-cpu user profile maintenance examples ``ns`contents
Multi-cpu user profile maintenance examples

To help you understand, here are some annotated example configurations.  In
each of these examples, SYSA is the local host system where the changes occur.
SYSB is the remote system that is to be updated whenever changes occur on SYSA.
Remember, you can have both systems updating each other; SECURITY will
automatically avoid "infinite loops".

Example 1: NETRECV for two systems (SYSA and SYSB) in both directions.

Whenever a profile is changed on either system, the other system will RECEIVE
the change information and update the same profile.

   A) On SYSA, add the following:

      Filename: SECURCON.DATA.VESOFT
         $SYS-NAME "SYSA"
         $NET-SEND SYSB

      Filename: NETRECV.DATA.VESOFT
         $FROM-SYS SYSB SYSB

      Filename: SYSB.NETRECV.VESOFT
         $RECEIVE @ !HPJOBNAME,!HPUSER.!HPACCOUNT @.@

   B) On SYSB, add the following:

      Filename: SECURCON.DATA.VESOFT
         $SYS-NAME "SYSB"
         $NET-SEND SYSA

      Filename: NETRECV.DATA.VESOFT
         $FROM-SYS SYSA SYSA

      Filename: SYSA.NETRECV.VESOFT
         $RECEIVE @ !HPJOBNAME,!HPUSER.!HPACCOUNT @.@

   C) Finally, on both systems, execute the commands

         %SEC BACKG STARTJOB        (* If it's not already running *)
         %SEC BACKG START,NETRECV

Example 2: NETPUSH for two systems (SYSA and SYSB) in one direction.

Whenever a profile is changed on SYSA, it will log on to SYSB and change the
same profile (using $PUSH-IMMEDIATE).

   A) On SYSA, add the following:

      Filename: SECURCON.DATA.VESOFT
         $SYS-NAME "SYSA"
         $NET-SEND SYSB

      Filename: NETRECV.DATA.VESOFT
         $PUSH-IMMEDIATE SYSB

   B) On SYSB, add the following:

      Filename: SECURCON.DATA.VESOFT
         $SYS-NAME "SYSB"

      Filename: NETRECV.DATA.VESOFT
         $FROM-SYS-PUSHED SYSA SYSA

      Filename: SYSA.NETRECV.VESOFT
         $RECEIVE @ !HPJOBNAME,!HPUSER.!HPACCOUNT @.@

   C) Finally, on both systems, execute the commands

         %SEC BACKG STARTJOB        (* If it's not already running *)
         %SEC BACKG START,NETRECV

Example 3: large network model.

This example is much more complex.  Imagine a large network of systems
scattered across the country.  Using X.25, each one can connect with each other
one, but they shouldn't be continually connected.  Instead, what we will do is
have each system dial-in to a "master" or "hub" system every time a profile is
changed.  Then, once a night, the "hub" will send all of the changes made to it
during the day to each of the "slave" or "spoke" systems.

Using this plan, the "hub" will always have the current SECURITY configuration
of all of the "spokes", and each "spoke" will be updated with changes from all
the other "spokes" at the end of the day.  A user who changes his password on a
"spoke" will be able to use his new password on the "hub" virtually
immediately, and on other "spokes" starting tomorrow.

Are you ready?  Take a deep breath; here we go...

   A) On system HUB, add the following:

      Filename: SECURCON.DATA.VESOFT
         $SYS-NAME "HUB"
         $NET-SEND ^SPOKELST.NETRECV.VESOFT

      Filename: SPOKELST.NETRECV.VESOFT
         SPOKE01
         SPOKE02
         ...

      Filename: NETRECV.DATA.VESOFT
         $PUSH-INTERMITTENT SPOKE01
         $PUSH-INTERMITTENT SPOKE02
         ...
         $FROM-SYS-PUSHED ^SPOKELST SPOKECON

      Filename: SPOKECON.NETRECV.VESOFT
         $RECEIVE @ !HPJOBNAME,!HPUSER.!HPACCOUNT @,@.@

   B) On each SPOKE system (SPOKE01, SPOKE02, ...), add the following:

      Filename: SECURCON.DATA.VESOFT
         $SYS-NAME "SPOKE01"
         $NET-SEND HUB

      Filename: NETRECV.DATA.VESOFT
         $PUSH-IMMEDIATE HUB
         $FROM-SYS-PUSHED HUB HUB

      Filename: HUB.NETRECV.VESOFT
         $RECEIVE @ !HPJOBNAME,!HPUSER.!HPACCOUNT @,@.@

   C) On all systems (HUB and SPOKEs),

         %SEC BACKG STARTJOB        (* If it's not already running *)
         %SEC BACKG START,NETRECV

   D) On system HUB only:

         %SEC BACKG START,NETPUSH

      The NETRECV task on the HUB merely waits for a SPOKE to send a change,
      which it then posts to the SECURITY user profiles on the HUB.

      The NETRECV task on each SPOKE does two things: sends changes to the HUB
      throughout the day (by logging on to the HUB, sending the change, and
      then logging off), and at night, when NETPUSH on the HUB sends the
      changes to the spokes, NETRECV on each spoke posts the changes to the
      SECURITY user profiles.


LOGON SECURITY AND MULTI-CPU SITES (REVIEW)``contents`news
LOGON SECURITY AND MULTI-CPU SITES (REVIEW)

Here is a review of the configuration files and corresponding keywords that are
required in order to use these network related features:

Filename
   $-Keyword          Definition and usage

SECURCON.DATA
   $SYS-NAME          Defines the name of the LOCAL system.  This keyword has
                      one parameter, the name of this system, and may be up to
                      8 characters in length.  This keyword should appear only
                      once in the file.

                      The name of a HOST system is the value of the $SYS-NAME
                      parameter of the host system's SECURCON file.

   $NET-SEND          Identifies the name of the REMOTE system that will
                      receive change information.  This keyword has one
                      parameter, the name of the system that is to receive data
                      from this system.  This keyword may be repeated or the
                      parameter can be a filename prefaced with "^" to indicate
                      an indirect file.  If an indirect file is used, each line
                      should be the name of a system to receive data.

   ;HOST=             (as part of a userset) Indicates that the immediately
                      preceding portion of the userset should be validated
                      against the HOST system and not the LOCAL system.  This
                      "immediately preceding" portion is also known as the
                      "host portion" of a userset, everything else is the
                      "local portion".  A user is considered a member of the
                      userset if they are a member of the HOST portion of the
                      userset on the specified HOST system AND a member of the
                      LOCAL portion on the LOCAL system.

                      The value of this parameter should be the same as the
                      HOST system's $SYS-NAME parameter, but may contain "@" to
                      indicate ALL remote hosts, or "?@" to indicate any host
                      EXCEPT itself (also known as a "loopback" logon).

                      Note that this is a part of a userset and not a separate
                      keyword.

   $NO-HOST-CHECK     Indicates which "host systems" should be excluded from
                      ;HOST= processing.  The parameter for this keyword is
                      actually a pattern to compare against the DSLINE node
                      name of the host system and may contain wildcard
                      characters.

                      When a user first logs onto a LOCAL system, SECURITY
                      tries to access a file on the HOST system using a
                      facility known as Remote File Access (RFA).  If the HOST
                      system doesn't support RFA, the session may hang for
                      several minutes until the request "times out".  By
                      including this keyword, you indicate to our program that
                      any logons FROM the specified system do NOT support RFA,
                      so we don't attempt to access files on the host.  In this
                      case, we treat the incoming logon as if it were from a
                      hardwired terminal instead of a network logon.

                      NOTE: in order to be effective, this keyword MUST appear
                      before any userset that makes use of the ;HOST= syntax.

NETRECV.DATA
   $FROM-SYS          Identifies a system to PULL data from.  There are two
                      parameters for this keyword, The first is the NODE name
                      (the name you would use in a :DSLINE command) and the
                      second is the name of a configuration file that contains
                      $RECEIVE commands (see below).  This keyword should be
                      repeated for each system that will have data to transmit
                      to this system or the first parameter may be an indirect
                      file that contains a list of node names.
                      NOTE: due to the way this is implemented, the node name
                      must be 8 characters or less.  For systems that have
                      longer DSLINE node names, you can use an alias as
                      follows:

        $FROM-SYS SYSNAME=NODE.DOMAIN.ORGANIZATION configfile

   $FROM-SYS-PUSHED   Identifies a system that will PUSH data to this system.
                      This keyword has two parameters, the name of the system
                      that is transmitting the change information (the
                      $SYS-NAME parameter of the transmitting system's SECURCON
                      file) and the second is the name of the configuration
                      file that contains $RECEIVE commands (see below).  This
                      keyword should be repeated for each system that will push
                      data to this system or the first parameter may be an
                      indirect file that contains a list of node names.

   $PUSH-INTERMITTENT Identifies the node name of a system to PUSH data to upon
                      demand (via %SEC NETPUSH).  This keyword has one
                      parameter, the node name to use for transmitting the
                      change information.  This should be the same name you
                      would use in a :DSLINE command.
                      NOTE: due to the way this is implemented, the node name
                      must be 8 characters or less.  For systems that have
                      longer DSLINE node names, you can use an alias as
                      follows:

        $PUSH-INTERMITTENT SYSNAME=NODE.DOMAIN.ORGANIZATION

   $PUSH-IMMEDIATE    Identifies the node name of a system to PUSH data to when
                      it is changed on this system.  This keyword has one
                      parameter, the node name to use for transmitting the
                      change information.  This should be the same name you
                      would use in a :DSLINE command.
                      NOTE: due to the way this is implemented, the node name
                      must be 8 characters or less.  For systems that have
                      longer DSLINE node names, you can use an alias as
                      follows:

        $PUSH-IMMEDIATE SYSNAME=NODE.DOMAIN.ORGANIZATION

sysname.NETRECV       "sysname" is the name of the configuration file for each
                      system identified in the NETRECV.DATA file with a
                      $FROM-SYS or $FROM-SYS-PUSHED keyword.

   $RECEIVE           Indicates what %SEC actions (ADD, CHANGE, or DELETE) will
                      be applied to profiles on the RECEIVING system.

Network Security Loopholes:


Loopholes: Network related``contents`news
Loopholes: Network related

One significant problem that remains for HP3000 users who rely on UDCs to
control logon access to their HP3000 is network-originated file transfer
operations.

When using, for example, the auto-logon feature of NS, a programmatic logon
occurs on the HP3000 that doesn't result in the CI being run.  In this case,
any OPTION LOGON UDCs that have been defined for the user ID being used are not
executed.  SECURITY relies on the execution of an OPTION LOGON UDC to intercept
the logon, and as this does not occur, the auto-logon succeeds without SECURITY
being able to control access to the system.

In this case, system access is only protected by MPE passwords at the User,
Account or Group levels, but not by additional SECURITY password protection.

CLOSING THE LOOPHOLE


Loopholes: closing``contents`news
Loopholes: closing

We have taken advantage of a new MPE/iX operating system Architected Interface
Facility known as Procedure Exits (AIF:PE) to intercept all logon attempts on
the HP3000.  We now make use of the ability to trap all logons (independently
of a CI process being created) to close this security loophole.

Our use of AIF:PE does not require that you purchase any additional software
from HP, but does require you to be using MPE/iX 4.0 or later.  The commands
described here will not function on operating system releases prior to MPE/iX
4.0.

THEORY OF OPERATION


HELLO trap theory of operation``contents`news
HELLO trap theory of operation

The solution to closing this security loophole has been implemented as follows:

First, all system logon attempts are intercepted and processed by SECURITY
before they are evaluated by MPE.  During this processing, we determine if this
is a network-originated logon, and if so, we check if the logon attempt is
authorized or not.  If the HELLO command contains embedded SECURITY passwords,
we use a permanently running background task to authenticate the supplied
password.

A special configuration file (HELLO.DATA.VESOFT) is used to define what actions
are to be taken when a logon command is intercepted.  In the case of network
logons, you can specify that they be handled in any of three different ways:
they may be Refused unconditionally, Allowed unconditionally or Checked to see
if the user is authorized to logon.  You may define which strategy is to be
used as a function of the logon ID supplied when attempting to connect to the
system.

If the logon trap determines that a network logon is being attempted, and that
a SECURITY password has been supplied, it then needs to authenticate the
supplied password.  This checking is performed by a new task (HELLO) run by
VESOFT's BACKG background job.  For this reason, the BACKG job must be
executing for network checking to be performed, and the HELLO task must have
been started.

If you only wish to unconditionally Allow or Refuse network logons, then you
don't need to run the BACKG HELLO task at all.

Checking SECURITY/3000 passwords during network logons


Checking embedded SECURITY passwords during logon``contents`news
Checking embedded SECURITY passwords during logon

If you decide to check incoming network logons for SECURITY passwords, then the
logon trap needs to be able to verify that the remote user attempting to logon
has specified a valid jobsession name, and also that they know the
corresponding SECURITY password.

As it is not possible to prompt network users for SECURITY passwords during
network logon attempts, another way had to be found to allow us to authenticate
a user's identity.

To allow this to occur, we extended HP's traditional HELLO command syntax to
allow specification of a SECURITY password within the logon string immediately
following the jobsession name.

When checking of network logon attempts has been configured, qualifying network
logons must embed the user's SECURITY password within the logon string.  The
way the logon string is specified depends on the networking product being used
and the platform from which the attempt originates.


HELLO Examples: how to access a system with the HELLO task active
following examples show how to specify the extended logon syntax from a
number of environments; they show how to specify a SECURITY password of 'pw1'
associated with an HP3000 logon to 'name,user/pw2.acct/pw3,group/pw4'.


HELLO Example 1: DSLINE autologon file transfer from another HP3000
1: DSLINE autologon file transfer from another HP3000

  :DSLINE nodeid=nodename;logon="name/pw1,user/pw2.acct/pw3,group/pw4"
  :FILE infile=file.group.account;DEV=nodeid#
  :FCOPY FROM=*infile;to=

  The FILE command may also be used with the following syntax:

  :FILE infile=file.group.account:nodeid#


HELLO Example 2: ARPA/FTP connection from another HP3000
2: ARPA/FTP connection from another HP3000

  :RUN FTP.ARPA.SYS
  ftp> open nodename
  Name: name/pw1,user/pw2,account/pw3,group/pw4

  You may not enter the SECURITY password at FTP's 'Password:' prompt, although
  you may enter any required MPE passwords this way.


HELLO Example 3: DSCOPY auto logon file transfer from an HP3000
3: DSCOPY auto logon file transfer from an HP3000

  The logon string may be specified using the DSLINE command, as shown in
  Example 1 above or it may be specified within the DSCOPY command itself, as
  shown below:

  :DSCOPY fromfile TO tofile:nodename[NAME/pw1,USER/pw2.ACCT/pw3,GROUP/pw4]

(Note: In this example, the "[" and "]" characters are part of the required
syntax of the :DSCOPY command, not an indication of optional parameters)


HELLO Example 4: DSCOPY auto logon file transfer from an HP9000
4: DSCOPY auto logon file transfer from an HP9000

  #dscopy -r fromfile nodename#NAME/pw1,USER/pw2.ACCT/pw3#tofile

  The following syntax is also acceptable:

  #dscopy -r fromfile nodename#"name/pw1,user/pw2.acct/pw3,group/pw4"#tofile


HELLO Example 5: Programmatic use of RPM intrinsics from an HP3000
5: Programmatic use of RPM intrinsics from an HP3000

  If you use RPM (Remote Process Management) intrinsics to control programs on
  remote machines, you can include the SECURITY password as part of the login
  information.  When calling the RPMCREATE intrinsic, however, you cannot
  specify the SECURITY password using the intrinsic's password parameter,
  instead you must embed it within the login parameter, as shown below:

  location := 'nodename';
  login    := 'name/pw1,user.acct,group';
  password := 'pw2,pw3,pw4';
  rpmcreate (...

Note that any of the above logon attempts will fail if HELLO trap is not turned
on: MPE/iX cannot handle the extended syntax if the HELLO trap is not able to
intercept it.

All network products limit the entire length of the logon string to some
predefined limit which may not take into account the extended syntax described
above.  For this reason, it may not be possible to make use of the extended
syntax in cases where the existing logon string elements are all present and
are all at or near 8 characters long.  If this occurs, you will have to reduce
the length of some or all of the elements in the logon string until the total
length is acceptable.

CONFIGURING HELLO TRAP FOR REMOTE ACCESS SECURITY


Configuring HELLO trap for REMOTE ACCESS``contents`news
Configuring HELLO trap for REMOTE ACCESS

The HELLO.DATA.VESOFT configuration file is used to define the actions
performed by HELLO trap.  It must be kept unnumbered.  The file may contain any
number of '$' prefixed keywords, which may be followed by one or more
parameters.  These parameters must be on the same line, and must be delimited
by one or more blanks.  The file may contain blank lines, and comments
delimited by pairs of (* and *).

The following keywords are available (others are documented in the section
"Configuring HELLO trap for Logon Security"):


CONFIG NETWORK, HELLO trap keyword``contents`news
$CONFIG NETWORK, HELLO trap keyword

 $CONFIG NETWORK allow | refuse | check <logon ID>
                             Specifies how network-originated logon attempts
                             should be handled.

                             One of the following keywords should be supplied
                             to indicate how the logon attempt should be
                             handled if the logon ID field matches:

                               ALLOW  ..  Allow logon unconditionally
                               REFUSE ..  Refuse logon unconditionally
                               CHECK  ..  Check logon via BACKG HELLO task

                             If the optional logon ID field is specified, then
                             the $CONFIG options will only be applied if the
                             actual logon being attempted matches the logon ID
                             field.  If logon ID is not supplied, a default
                             value of '@.@' is assumed.

                             logon ID may contain wildcard characters.

                             The $CONFIG command also accepts the optional NODE
                             <pattern> specification.  Refer to the section
                             'Limiting access by remote machine name/address'
                             for details on how to limit the scope of $CONFIG
                             commands to specific remote machines.


CONFIG NETJOB, HELLO trap keyword``contents`news
$CONFIG NETJOB, HELLO trap keyword

 $CONFIG NETJOB allow | refuse <logon ID>
                             Specifies how network-originated job streams
                             should be handled.

                             Network-originated jobs are jobs that are
                             submitted by users who have logged on via FTP and
                             submit a job using the FTP's 'SITE STREAM'
                             command.

                             One of the following keywords should be supplied
                             to indicate how the job stream should be handled
                             if the logon ID of the job matches:

                               ALLOW  ..  Allow job stream unconditionally
                               REFUSE ..  Refuse job stream unconditionally

                             If the optional logon ID field is specified, then
                             the $CONFIG options will only be applied if the
                             actual logon being attempted matches the logon ID
                             field.  If logon ID is not supplied, a default
                             value of '@.@' is assumed.

                             logon ID may contain wildcard characters.

                             $CONFIG NETJOB REFUSE @.@ is used as the default
                             setting.


CONFIG TIMEOUT, HELLO trap keyword``contents`news
$CONFIG TIMEOUT, HELLO trap keyword

 $CONFIG TIMEOUT allow | refuse
                             Specifies whether timed-out checked network logon
                             attempts should be allowed or refused.

                             By default, timed-out network logon attempts are
                             allowed.


CONFIG BACKUP, HELLO trap keyword``contents`news
$CONFIG BACKUP, HELLO trap keyword

 $CONFIG BACKUP allow | refuse
                             If the internal files used by the logon trap are
                             locked by a system backup, then the VESOFT HELLO
                             trap will be unable to check the supplied SECURITY
                             password.  This command specifies whether network
                             logon attempts that cannot be checked due to
                             system backup should be allowed or refused.

                             By default, such failed network logon attempts are
                             refused.


TIMEOUT, HELLO trap configuration keyword``contents`news
$TIMEOUT, HELLO trap configuration keyword

 $TIMEOUT <value>           Specifies timeout (in seconds) to be applied to
                             network-originated logon attempts.  This is
                             necessary to prevent network logon attempts from
                             hanging indefinitely if the BACKG HELLO task is
                             not active.

                             If this keyword is not specified, a default value
                             of 120 seconds is used.

                             The action to be taken following a timeout is
                             specified using the $CONFIG TIMEOUT keyword.


MPELOG, HELLO trap configuration keyword``contents`news
$MPELOG, HELLO trap configuration keyword

 $MPELOG <level>            Specifies level of logging desired to MPE's
                             LOG####.PUB.SYS logfiles.

                             This logging is implemented by writing log
                             messages to the system console.  MPE's CONSOLE
                             logging must also be turned on for the console
                             messages to be stored in the system log files.

                             See "Logging Levels" section below for details on
                             available logging levels.


DEBUGLOG, HELLO trap configuration keyword``contents`news
$DEBUGLOG, HELLO trap configuration keyword

 $DEBUGLOG <level>          Echoes log messages to the BACKG HELLO task's
                             $STDLIST file: SHELLO.DATA.VESOFT.

                             See "Logging Levels" section below for details on
                             available logging levels.


SECLOG, HELLO trap configuration keyword``contents`news
$SECLOG, HELLO trap configuration keyword

 $SECLOG <level>            Specifies level of logging desired to the SECURITY
                             logfile LOG20.DATA.VESOFT.

                             See "Logging Levels" section below for details on
                             available logging levels.

                             SECURITY log records generated by the HELLO trap
                             may be retrieved using the SECURITY LISTLOG
                             command as follows:

                               %SEC LISTLOG OPHELLO

The entire HELLO.DATA.VESOFT file is parsed during every logon attempt, hence
we don't recommend that you add unnecessary entries to the file.  For proper
sequence of entries within the configuration file see the section "Configuring
HELLO trap for Logon Security".

USING HELLO TRAP


USING HELLO trap``contents`news
USING HELLO trap

Allowing, Refusing or Checking Network Logon Attempts


ALLOWING, REFUSING or CHECKING LOGON ATTEMPTS``contents`news
ALLOWING, REFUSING or CHECKING LOGON ATTEMPTS

You have the ability to specify that Network-originated logon attempts be
unconditionally allowed or refused or that they be checked, in which case the
jobsession name and SECURITY password must be supplied as part of the logon
string.

If you specify that network logons are unconditionally allowed or refused, you
may also define specific logon IDs as exceptions.  The following commands in
the HELLO.DATA.VESOFT configuration file can be used to define network logon
access:

  $CONFIG NETWORK ALLOW  <logon ID>   (allow matching network logons)
  $CONFIG NETWORK REFUSE <logon ID>   (refuse matching network logons)
  $CONFIG NETWORK CHECK  <logon ID>   (check matching network logons)

If logon ID is not specified then all network logon attempts will match the
$CONFIG command.

The HELLO.DATA.VESOFT configuration file is parsed from start to end during
every logon.  The logon trap tracks all instances of the above keywords that
match the logon ID being attempted, and modifies its decision to allow, refuse
or check the logon attempt in the light of the last $CONFIG entry that matches.

We recommend that you use $CONFIG NETWORK to specify the general strategy to be
applied to incoming network logons, and then modify this as necessary for
specific logons that you wish to be handled differently.

As an example, if the HELLO.DATA.VESOFT configuration file contains the
following entries:

  $CONFIG NETWORK REFUSE
  $CONFIG NETWORK ALLOW   user.dialin
  $CONFIG NETWORK ALLOW   mgr.telesup
  $CONFIG NETWORK CHECK   hponly,manager.telesup

then all network users will be prevented from connecting to the HP3000, unless
they logon as USER.DIALIN or USER.DATAIN, in which case access will be allowed
or unless they logon as HPONLY,MANAGER.TELESUP, in which case a valid SECURITY
password must also be specified.

The following configuration would allow HELLO trap to be tested for specific
test logon IDs, without interfering with other system activity:

  $CONFIG NETWORK ALLOW
  $CONFIG NETWORK CHECK  testname,testuser.testacct,testgrp
  $CONFIG NETWORK REFUSE testnam2,testuse2.testacc2,testgrp2

The $CONFIG command's optional logon ID field accepts a subset of the MPEX and
SECURITY 'simple userset' syntax.  Logon ID may include the following wildcard
characters:

  @  ..  matches zero or more alphanumeric characters
  ?  ..  matches a single alphanumeric character
  #  ..  matches a single numeric character

The session name and group name fields are optional and will default to the "@"
character if not specified.  Blank session or group names, however, only match
logon strings that do not contain a session or group name.  For example:

   USER.ACCOUNT      matches    GEORGE,USER.ACCOUNT
  ,USER.ACCOUNT      matches           USER.ACCOUNT,PUB
   USER.ACCOUNT,     matches      FRED,USER.ACCOUNT
  ,USER.ACCOUNT,     matches           USER.ACCOUNT        only!

  ,USER.ACCOUNT   does NOT match  FRED,USER.ACCOUNT,PUB
   USER.ACCOUNT,  does NOT match       USER.ACCOUNT,DATA
  ,USER.ACCOUNT,  does NOT match    ME,USER.ACCOUNT,MYGROUP

LOGGING LEVELS


HELLO TRAP logging levels``contents`news
HELLO TRAP logging levels

You may use the $MPELOG, $SECLOG and $DEBUGLOG commands to specify the level of
logging detail desired.  The commands should be followed by a numeric 'level'
parameter, which will be interpreted as shown below.  Each log level implies
all lower-numbered log levels.

   Level       Action
    0 no logging performed (default for $SECLOG)
    1 log internal errors  (default for $MPELOG)
    2 log refused network logon and PEUTIL disallow attempts
    3    log network logon attempts that are refused or allowed due to timeout
         (HELLO task not responding)
    4 log allowed network logon and PEUTIL disallow attempts
    6 log use of $NOPARM
    8 log use of embedded MPE passwords (not yet implemented)
   10 log use of $HELLO
   11 log use of $CHANGE

Any combination of the $LOG commands may be specified; the log levels
associated with each command are independent of each other.

Modifying the HELLO.DATA.VESOFT configuration file


MODIFYING THE HELLO.DATA CONFIGURATION FILE``contents`news
MODIFYING THE HELLO.DATA CONFIGURATION FILE

This file may be modified at any time, regardless of whether the VESOFT HELLO
trap or the BACKG HELLO task are active or not.  Any changes to the file take
effect immediately.  You don't need to stop and restart HELLO trap or the BACKG
HELLO task for changes to take effect.

Notes on use of $HELLO command


HELLO, HELLO trap configuration keyword``contents`news
$HELLO, HELLO trap configuration keyword

The $HELLO command may be used to define abbreviated logons.  Optional HELLO
command parameters may still be specified when an abbreviated logon is being
used, as shown by the following examples:

If the following $HELLO definition is placed in the configuration file:

  $HELLO PAUL PAUL,MANAGER.SYS

then any of the following logon command forms may be used:

  :HELLO PAUL
  :HELLO PAUL;HIPRI
  :HELLO PAUL,PUB
  :HELLO PAUL,PUB;HIPRI

The following logon command may still be used: $HELLO definitions are ignored
when an explicit USER.ACCOUNT has been specified:

  :HELLO PAUL,OPERATOR.SYS

This $HELLO definition would have no effect in the following cases:

  :HELLO XPAUL
  :HELLO PAULINE

If the $HELLO definition also specifies a logon group, as follows:

  $HELLO  PAUL  PAUL,MANAGER.SYS,PUB

then the following logon form may not be used:

  :HELLO PAUL,MPEXL

HELLO.DATA.VESOFT file syntax errors


SYNTAX ERRORS IN THE HELLO.DATA FILE``contents`news
SYNTAX ERRORS IN THE HELLO.DATA FILE

Any syntax errors discovered in the HELLO.DATA.VESOFT configuration file will
be displayed on the system console when they are encountered during logon
attempts.  Any line containing a syntax error will then be ignored, and have no
further effect on logon attempts.

Activating HELLO trap


Activating HELLO trap``contents`news
Activating HELLO trap

To start up the BACKG HELLO task and to enable HELLO trap, simply enter the
following commands:

  :RUN MAIN.PUB.VESOFT
  %BACKG START, HELLO
  %BACKG STARTJOB

If you own only SECURITY/3000, enter the commands this way:

  :RUN MAIN.PUB.VESOFT,SEC
  %SEC BACKG START,HELLO
  %SEC BACKG STARTJOB

The %BACKG START,HELLO command need only be issued once: the BACKG job
automatically restarts all tasks that were active during its previous run,
whenever and however it is started.

Activating VESOFT BACKG job automatically at system start-up


Activating the BACKG job automatically at start-up``contents
Activating the BACKG job automatically at start-up

When the system is restarted, no procedure exit based traps are active.  To
fully protect your system, the HELLO trap must be turned on every time the
system is restarted.  Since the BACKG job automatically restarts all
previously-active tasks (including the HELLO trap), we recommend that you
launch the BACKG job whenever the system is started.

The following method will allow you to launch the BACKG job automatically
whenever your system is started, without having to supply passwords, and
without opening up any security loopholes.

First, log on as MANAGER.SYS.

Then modify (or build if necessary) the file SYSSTART.PUB.SYS to contain the
following lines (if the file contains multiple sections separated by a "*" in
the first column, place these lines inside the STARTUP section):

  STARTUP
  STREAMS 10
  LIMIT 1
  STREAM SYSSTART.JOB.VESOFT
  other optional STARTUP commands...
  *
  other optional SYSSTART sections...

The LIMIT command is needed to ensure that the Job Limit is at least 1; you can
replace this with larger values if required.

When your VESOFT account was installed, we created the passwordless
BA-capability user SYSSTART.VESOFT.  This user is protected from unauthorized
batch access by an OPTION LOGON user-level UDC (LOGONUDC.SYSSTART.VESOFT),
which limits its use to the particular case where the file SYSSTART.JOB.VESOFT
is STREAMed from within the file SYSSTART.PUB.SYS.  The LOGON UDC in turn
starts up the VESOFT BACKG job, and then logs the user off.

When the BACKG job is started this way (and ONLY when it is started this way),
the BACKG job will execute the contents of the file SYSINI.DATA.VESOFT (if the
file exists) as it initializes, and before it starts up any of the BACKG tasks.
This file may be used to perform initialization tasks (such as starting up your
LAN) that must be performed once whenever the system starts up, but which
cannot easily be executed from inside a SYSSTART.PUB.SYS file.

Note: For this method to work, a %BACKG START,HELLO command must have been
      issued prior to the system starting up.  You can issue the %BACKG SHOW
      command at any time to verify that the BACKG HELLO task is either
      executing or pending.

Note: The SYSSTART file is only executed automatically at system start-up if
      it's creator was MANAGER.SYS.  If the file was modified by any other
      user, it will be ignored during system start-up.

Overriding automatic execution of SYSSTART during system start-up


Overriding automatic execution of SYSSTART``contents`news
Overriding automatic execution of SYSSTART

If you have modified SYSSTART.PUB.SYS to automatically stream the BACKG job (as
described above), it's still possible to inhibit execution of the SYSSTART file
during system start-up.  To inhibit execution of SYSSTART, specify the
;NOSYSSTART parameter when entering the START command at the system ISL prompt.

Stopping HELLO and LOGON traps


Stopping the %BACKG HELLO and LOGON tasks with PEUTIL``contents
Stopping the %BACKG HELLO and LOGON tasks with PEUTIL

Stopping the BACKG job does not completely stop the VESOFT BACKG HELLO and
LOGON tasks.  If you need to turn off the HELLO or LOGON tasks, issue the
individual %BACKG STOP,HELLO or %BACKG STOP,LOGON commands.

Since the PEUTIL.PUB.SYS program may be used to temporarily inhibit execution
of all system AIF:PE based traps (used internally by both HELLO and LOGON BACKG
tasks), the HELLO and LOGON traps may also be disabled as follows:

      :RUN PEUTIL.PUB.SYS
      peutil > disallow
      peutil > exit

Note that when the PEUTIL program is used in this way, all system AIF:PE traps
are suspended.  They may be reactivated by entering the following commands:

      :RUN PEUTIL.PUB.SYS
      peutil > allow
      peutil > exit

If you include ";susp=false" on the "disallow" command, i.e.  you type:

      :RUN PEUTIL.PUB.SYS
      peutil > disallow ;susp=false
      peutil > exit

then ALL system AIF:PE traps are disabled and removed from memory.  In order to
restart HELLO trap after using this method of stopping the trap, you must use
the %BACKG START,HELLO and/or %BACKG START,LOGON commands.

Other important notes to remember when using this method of stopping the HELLO
or LOGON traps:

  * PEUTIL commands must be entered in lower case.

  * The PEUTIL program inhibits all AIF:PE traps system-wide.  As this may
    effect other utilities and facilities, we recommend that this only be used
    in an emergency.

  * Access to PEUTIL.PUB.SYS's "disallow" command may be restricted (or
    blocked) using the configuration file's $PEUTIL command.

%BACKG HELLO task priority


%BACKG HELLO task priority``contents`news
%BACKG HELLO task priority

As the response time of the BACKG job's HELLO task is critical when checking
supplied SECURITY passwords, we have modified BACKG so that the HELLO task
executes at a linear priority of 151.  You may override this priority via the
BACKG configuration file (BACKGINI.DATA.VESOFT) by adding a line redefining the
HELLOPRI variable, for example:

    SETVAR HELLOPRI "CS"
or    SETVAR HELLOPRI "200"

We recommend, however, that you do not change the default value.

If the BACKG HELLO task executes at a lower priority (and especially if it
executes in 'D' que), there is a significant chance that network logons may
timeout waiting for the HELLO task to authorize them.  Response time of session
and job logons are not affected by the priority of the HELLO task.

Determining the state of HELLO trap


Determining the state of the %BACKG HELLO task``contents`news
Determining the state of the %BACKG HELLO task

Unfortunately, it's not easy to see whether or not HELLO trap is active at any
given moment since HP doesn't provide a specific command to determine what
AIF:PE traps are active.  However, there is a way to determine what traps are
active by using the MPE/iX debugger.

The MPE/iX DEBUG command has a macro called 'aif_pelist' that will display all
active AIF:PE bindings.  To use this macro, enter the following commands:

  :debug                               <<<<< PM user logon required
  DEBUG/iX x.nn.nn
  nmdebug > macstart                   <<<<< enter 'macstart'
  Welcome to the DAT Macro facility.
  Enter your selection now: 1          <<<<< reply '1' for OS macros
  nmdebug > aif_pelist                 <<<<< enter 'aif_pelist'

If this doesn't work, try typing %ZZAIFPE from within MPEX.  This MPEX command
file performs essentially the same sequence as shown above, but doesn't require
you to input any extra information.

The following information is displayed:

  P T                                                             S
  R Y                                                             E
  O P Procedure              Procedure              Lib Prod Bind L B
  C E Name                   Library                Pri Name ID   F Q
  - - ---------------------- -------------------- ----- ---- ---- - -
  T   pe_allow_not           NL.PUB.SYS               1         0
  H I penot                  HELLO.PE.VESOFT          3 MPEX  255 Y Y
  T   slo_get_comnd          NL.PUB.SYS               1         0
  H I hello                  HELLO.PE.VESOFT          4 MPEX  255 Y Y

This displays shows that two AIF:PE traps are currently active:

  procedure penot in HELLO.PE.VESOFT intercepts pe_allow_not in NL.PUB.SYS
  procedure hello in HELLO.PE.VESOFT intercepts slo_get_comnd in NL.PUB.SYS

These two intercept procedures are used in the current release (28.), however,
the precise details may change in any new version.

You can't rely on the library containing HELLO trap being flagged as 'in-use'
to indicate if the trap is still active.  If HELLO.PE.VESOFT is flagged as
in-use, this only means that the trap had been active at some time since the
system was last restarted, not that it is still active.

Use the %BACKG SHOW command to report on the state of the BACKG job and its
HELLO task.

REMAINING SECURITY LOOPHOLES


Miscellaneous %BACKG HELLO topics``contents`news
Miscellaneous %BACKG HELLO topics
Remaining security loopholes

It is important to understand that the extra protection provided by our HELLO
trap is NOT provided in any of the following circumstances:

1)  Your system has been restarted, and the BACKG job's HELLO task has not yet
    been activated.

2)  The program PEUTIL.PUB.SYS is used at any time to suspend or disable AIF:PE
    traps system-wide.  Note that access to PEUTIL.PUB.SYS's "disallow" command
    may be restricted (or blocked) by using the configuration file $PEUTIL
    command.

When any of these circumstances occur, regardless of whether the BACKG HELLO
task is active or not, your system behaves exactly as if HELLO trap does not
exist:  any network security loopholes are present, and SM users may bypass
logon UDCs by specifying HELLO...;PARM=-1 or -2.  Only while HELLO trap is
active are these loopholes closed.

Known Problems


Known problems``contents
Known problems

By default on MPE/iX 4.0 and later systems, anyone who can access the program
file PEUTIL.PUB.SYS is able to turn off AIF:PE traps system-wide.  Although we
have closed this loophole by adding the configuration file $PEUTIL keyword, if
you specify $PEUTIL ALLOW, this protection will be turned off.  In this case,
anyone who runs the program (or a copy of it located in any PM group) will be
able to turn off Procedure Exits system-wide.

If you use the HELLO.DATA.VESOFT file $CHANGE or $HELLO keywords to define
hello synonyms or abbreviated logons, these may only be used at the initial
logon prompt.  They will not work at the CI's ':' prompt once you are logged
on.

Updating VESOFT software when using HELLO trap


Updating VESOFT software with the %BACKG HELLO task``contents`news
Updating VESOFT software with the %BACKG HELLO task

HELLO trap routine is located in the NMXL file HELLO.PE.VESOFT.  This file is
flagged as in-use once procedure exits have been activated, and (because of
AIF:PE internal limitations) remains flagged in-use even after all procedure
exits have been disabled -- for this reason it is difficult to update this file
when installing future updates of our software.

If you had been using AIF:PE traps, you will need to restart your system once
following normal completion of the VESOFT installation job.  The install job
has been modified to generate a console message warning that a system restart
is necessary, when this is the case.

Limiting access by name/address of source machine


Limiting access by NAME/ADDRESS of host machine``contents`news`node
Limiting access by NAME/ADDRESS of host machine

Currently it is not possible for us to identify the source (node name or
network IP address) of the system from which network logon attempts originate.
To allow you some control over network access as a function of the particular
system being used, we have implemented a discretionary system which relies on
network users specifying their node name as part of their HP3000 logon string.

To specify the originating machine, specify its name or address using the new
'NODE=' parameter of the HELLO command, as shown in the following examples:

  HELLO MANAGER.ACCOUNTS; NODE=192.6.1.1

  HI DAVID; NODE=SHAKESPEARE     (assumes '$CHANGE HI HELLO')

NODE= may be used to specify any information, we don't limit the format in any
way, other than requiring that the string not contain embedded ';' characters
or the '(*' or '*)' strings.

The HELLO.DATA.VESOFT configuration file's $CONFIG command also now accepts
wildcard node specifications, as shown in the following examples:

  $CONFIG NETWORK allow @.@   NODE 192.6.1.5

  $CONFIG NETWORK check ab@,mgr.telesup   NODE @

The NODE keyword and associated node pattern are optional elements of the
$CONFIG command.  If NODE is not specified, '@' is assumed.

If the $CONFIG command includes a NODE specification, the node pattern will be
checked against the NODE parameter supplied by the logon attempt.  The $CONFIG
command will only be used if the NODE pattern matches the supplied NODE
parameter (and also only if any specified user ID matches that of the logon
attempt).

If the logon string does not contain any NODE parameter, then a blank NODE
string will be assumed.

This method, while relying on the 'honor' system for remote users to identify
their machines, does allow you flexibility in defined $CONFIG specifications
that only apply to selected remote machines.

The $CONFIG NETWORK NODE name may contain '@', '?' and '#' wildcard characters,
if required.

The wildcard algorithm used to pattern-match NODE specifications differs from
that used to pattern-match user logon IDs, in that the '@' wildcard character
matches ANY character, including '.' and ','.

As a result of this, the single-character '@' pattern may be used to pattern
match an IP-address style NODE specification containing '.'s.  A pattern of
'192.@.@.@' (for example) could also be used, if required.


Batch security and job stream programming ``contents
Batch security and job stream programming


Introduction: Batch access security and job stream programming

STREAMX increases both your system security and your own productivity.  (For
additional information on batch access security, also see the chapter "How
SECURITY Passwords Work In Batch" in the Logon Security section.) It allows you
to avoid having to embed passwords into job streams (which is a major security
breach) and it also permits you to build job streams that are truly flexible --
that prompt the user for input, that check the environment to make sure certain
conditions are met (e.g.  whether or not a file exists, whether there's room in
it for the 1000 records the job stream will add to it, etc.), and that perform
complicated calculations based on user input and environment variables.

The next several sections will discuss:

   * using STREAMX to avoid embedded passwords,

   * building smart job streams using STREAMX,

   * other features of STREAMX, such as enhanced $STDLISTs, and

   * running STREAMX.

Here's what might happen when STREAMX is used to submit a sample job stream:

   The file MASTRPT.JOB.SYS            What is displayed on the terminal
                                       when you stream it

   ::ECHO YOU'RE STREAMING THE         YOU'RE STREAMING THE
   ::ECHO MASTER REPORT JOB STREAM     MASTER REPORT JOB STREAM
                                         --- STREAMX can display
                                             arbitrary data for the
                                             user at stream time
   ::IF HPDAY=1 or HPDAY=7 THEN          --- STREAMX can check
   ::  ECHO CAN'T DO THIS ON WEEKEND         environment information
   ::  EXIT                                  such as MPE's HPDAY JCW
   ::ENDIF
   ::TELLOP MASTRPT BEING SUBMITTED      --- STREAMX can execute
                                             arbitrary MPE commands
                                             at stream time:
   !JOB MASTRPT,MANAGER.SYS            ENTER MANAGER USER PASSWORD:
                                       ENTER SYS ACCOUNT PASSWORD:
                                         --- STREAMX prompts the user
                                             for the passwords!
   !RUN MASTRPT.PUB.UTIL
   ?ENTER LIST FILENAME?               ENTER LIST FILENAME? MYLIST
                                         --- STREAMX asks the user a
                                             question from the job
   TODAY-10                            --- STREAMX can calculate the
                                             results of expressions
                                             (e.g.  today's date - 10)
                                             and put them in the stream
   ?$CINTEGER$MAX NUMBER OF FILES?     MAX NUMBER OF FILES? 2500
                                         --- STREAMX can check user
                                             input (e.g.  to make sure
                                             it's an integer)
   !TELL HPUSER.HPACCOUNT DONE!      --- STREAMX can embed into the
                                             job stream information on
                                             who streamed the job
   !EOJ

And here's what the resulting job stream would look like if it was streamed by
MANAGER.PROD on Sep 14, 1988:

   !JOB MASTRPT,MANAGER/BOUNCE.SYS/KIPPERS    --- Passwords inserted
   !COMMENT   STREAM FILE MASTRPT.JOB.SYS     --- $STDLIST contains
                                                  stream file and
                                                  streaming user info!
   !COMMENT     STREAMED BY PETE,MANAGER.PROD,DEV ON LDEV 20
   !COMMENT    ON MON, SEP 14, 1988,  5:19 PM
   !RUN MASTRPT.PUB.UTIL
   MYLIST
   88/09/04                                   --- TODAY minus 10 days
   2500
   !TELL MANAGER.PROD DONE!                   --- :TELL back to the
                                                  originator
   !EOJ

Power like this, we believe, is hard to come by, but very useful in saving you
effort.  After all, why not have the computer do the hard work instead of your
having to do it yourself?


Embedded passwords -- why they're bad and how to avoid them ``contents
Embedded passwords -- why they're bad and how to avoid them

Why are embedded passwords bad? STREAMX lets you avoid embedded passwords --
instead of having your stream file's !JOB card say

   !JOB MANAGER/BOUNCE.SYS/KIPPERS

it can just say

   !JOB MANAGER.SYS

and the streaming user will be prompted for the MANAGER.SYS passwords at stream
time.  Why is this feature of STREAMX so good?

Embedded passwords have two great flaws:

   * Since they're stored in all your job streams, they can be easily seen
     since anybody who can read the job stream will see the passwords.

   * Even worse, they make it very hard to change passwords, since when you
     change a password you'll have to find and modify all the job streams that
     use it.  For the sake of system security, it's a very good idea to change
     passwords often; embedded passwords create a strong disincentive to do
     this important task.

Put together, these two problems have a very great effect on your system
security.

Now, how can you combat these problems? There are two alternatives:

   1) You can protect your job streams so that nobody has READ access to them,
      only EXECUTE access; this prevents people from finding out the passwords
      by just reading the stream file, since the stream file is now unreadable.
      However, if you make a mistake and forget to :ALTSEC the file after
      making a change or accidentally put it in a group which has Read access
      allowed to ANY, the file will be wide open; what's worse, this in no way
      makes passwords easier to change.  As long as you have embedded
      passwords, those vital periodic password changes will never get done.

   2) Or, you can use STREAMX, which eliminates the need for any embedded
      passwords (in !STARTSESS commands as well as !JOB lines!), plus supports
      smart job streams (more about them in subsequent chapters), plus makes
      life easier for the user by eliminating some unneeded password prompts
      (for instance, STREAMX will never prompt the system manager for a
      password -- it'll just submit the stream without issuing a prompt or
      requiring an embedded password).

Let's look for a moment at a sample job stream file:

   !JOB NIGHTRUN,OPERATOR.SYS; OUTCLASS=,1
   ...
   !STREAM ,*
   *JOB DISCLEAN,JANITOR.SYS; OUTCLASS=,1
   ...
   *STREAM ,#
   #JOB LOGDUMP,MGR.UTIL; OUTCLASS=,1
   ...
   #EOJ
   *STREAM APJOB.PUB.AP
   *EOJ
   !EOJ

This is a fairly common type of job stream.  The outer job, NIGHTRUN, does some
work, and then (at the very end) streams another job called DISCLEAN.  DISCLEAN
must be another job because it must log on as a different user ID
(JANITOR.SYS); it does more work of its own, and then streams two jobs in
parallel -- one called LOGDUMP and another that is stored in a different stream
file (APJOB.PUB.AP).  Of course, STREAMX works perfectly well on simple stream
files (that only involve, say, one job), but let's see how well it works on a
complex stream like the one shown above:

   :STREAM NIGHTRUN.SYSOP.SYS           (* This assumes that you've *)
                                        (* set our UDC that makes *)
                                        (* all :STREAM commands *)
                                        (* automatically run STREAMX *)

   STREAMX/3000  27Nymmdd  (c) VESOFT Inc, 1980  05:225

   JOB CARD = !JOB NIGHTRUN,OPERATOR.SYS; OUTCLASS=,1
   ENTER OPERATOR USER PASSWORD:  (* user types input, echo is off *)
   ENTER SYS ACCOUNT PASSWORD:    (* user types input, echo is off *)
   JOB CARD = *JOB DISCLEAN,JANITOR.SYS; OUTCLASS=,1
   ENTER JANITOR USER PASSWORD:   (* user types input, echo is off *)
                                  (* SYS account password not re-asked *)

   JOB CARD = #JOB LOGDUMP,MGR.UTIL; OUTCLASS=,1
   ENTER MGR USER PASSWORD:       (* user types input, echo is off *)
                                  (* if there's no UTIL account *)
                                  (* password, the user is not *)
                                  (* asked for it *)
   JOB CARD = !JOB APJOB,DBA.AP,DATA; OUTCLASS=,1
   ENTER DBA USER PASSWORD:       (* user types input, echo is off *)
   ENTER DATA GROUP PASSWORD:     (* user types input, echo is off *)

     #J1723

As you see, STREAMX prompted you for all the passwords for all the logons
mentioned in the job stream.  It even went into the file APJOB.PUB.AP and found
out which job card that file contained (APJOB,DBA.AP,DATA); then it prompted
for those passwords, too.  Of course, neither the NIGHTRUN.SYSOP.SYS nor the
APJOB.PUB.AP files were modified in any way; all the password insertions were
done in temporary files.

Even if you don't have very many nested jobs, the need to have any embedded
passwords can compromise your system security.  All it takes is one improperly
secured job stream with embedded passwords for somebody to see a password that
he shouldn't see; similarly, even if you cut down on the number of files that
have embedded passwords, how will you find them when it's time to change
passwords? You'll still have to scan through all your job streams to find the
ones that contain nested streams and embedded passwords.  In our opinion, the
only practical solution is to eliminate all embedded passwords.

STREAMX: HANDLING OF NESTED JOBS -- SPECIAL CASES


STREAMX: handling of nested jobs -- special cases ``contents
STREAMX: handling of nested jobs -- special cases

When you submit using STREAMX a job that streams another job, STREAMX looks at
both of these job streams to prompt you for any applicable passwords, execute
any :: commands that are contained in the jobs, and prompt for any data that
the jobs need input.

Looking at both the outer and the inner job is usually a good idea, but in a
few cases it can backfire:

   * The outer job may build a job stream and then submit it.  Not knowing
     about this, STREAMX will complain that the inner job doesn't exist
     (because it doesn't exist at the time the outer job is streamed).

   * The outer job may build the user, account or group under which the inner
     job will log on.  Again, not knowing about this, STREAMX will complain
     that the given user, account or group doesn't exist.

   * The outer job may stream itself (e.g.  to schedule itself to run at a
     later time).

What can you do in these situations?


STREAMXPERMNONESTERROR, STREAMX JCW to handle nested jobs

  * STREAMXPERMNONESTERROR

     If you do a :SETJCW STREAMXPERMNONESTERROR = 1 and stream a job (let's
     call it OUTER) which in turn tries to stream the job INNER, and the file
     INNER doesn't exist at the time OUTER is submitted, then STREAMX will not
     print an error message, but will rather cause OUTER to submit INNER (using
     STREAMX) at the appropriate time in the job.

     Of course, the very fact that INNER will not be read by STREAMX at the
     time the user streams OUTER means that INNER shouldn't try to prompt
     (using :: commands or the ?xxx? syntax) the user for any input;
     furthermore, if INNER doesn't contain passwords, you should make sure
     that, when it's submitted by OUTER, STREAMX will be authorized to
     automatically embed all the right passwords.  This can work either if
     INNER and OUTER log on the same way, if OUTER logs on with SM or AM or if
     there's a $NOPASS line in STREAMX.DATA.VESOFT that explicitly allows OUTER
     to submit INNER ($NOPASS and STREAMX.DATA.VESOFT are fully documented
     below, under "Allowing People To Stream Certain Files Without Password
     Prompts").


STREAMXPERMNONEST, STREAMX JCW to handle nested jobs

  * STREAMXPERMNONEST

     STREAMXPERMNONESTERROR only causes STREAMX not to look at the inner job if
     the file doesn't exist.  What if the user/account/group which the inner
     job is to log on as doesn't exist or the file exists but you don't want to
     use it (perhaps the outer job will modify the file)? Then, you should
     :SETJCW STREAMXPERMNONEST = 1, which will inhibit STREAMX from reading any
     inner job stream files.


STREAMXTEMPNONESTERROR, STREAMX JCW to handle nested jobs
STREAMXTEMPNONEST, STREAMX JCW to handle nested jobs

  * STREAMXTEMPNONESTERROR / STREAMXTEMPNONEST

     The STREAMXPERMNONESTERROR and STREAMXPERMNONEST JCWs, once set, will last
     for the remainder of the session or until you reset them to 0.  However,
     if you set the JCWs STREAMXTEMPNONESTERROR or STREAMXTEMPNONEST, then they
     will take effect only for the next job submitted by STREAMX.  Once that
     job is submitted, STREAMX will automatically reset those JCWs, so that
     subsequent executions will not be affected (unless you set them again).
     If you only want to avoid processing of the inner job stream occasionally
     (rather than permanently), we suggest that you use the TEMP JCWs, since if
     you use the PERM JCWs you might accidentally forget to reset them.

   * What if there is a particular job stream in which you know you never want
     to have the inner job processed? If you don't mind changing the file, just
     replace the !STREAM inside it by !STREAMX, and set up a system-wide UDC
     called STREAMX that behaves exactly like the STREAM UDC that we provide
     you in STRMUDC.PUB.VESOFT.  When reading the outer job, STREAMX will see
     the "!STREAMX" line but it will not process it as it would a "!STREAM"
     line; rather, it will just write it to the job stream, and when the job
     stream runs, it will execute the !STREAMX UDC and submit the inner job
     using STREAMX at the appropriate time.

   * Finally, what about jobs that stream themselves? STREAMX automatically
     detects this condition and does not loop, re-prompting for the passwords
     over and over.  Rather, the inner job is processed through STREAMX at the
     time the outer job streams it.

CONVENIENCE -- AVOIDING UNNEEDED PASSWORD PROMPTS


Convenience -- avoiding unneeded password prompts ``contents
Convenience -- avoiding unneeded password prompts

Now, you may have noticed a curious thing in the example given earlier (see
"Embedded Passwords -- Why They're Bad And How To Avoid Them").  The first job
card was for OPERATOR.SYS, and STREAMX prompted for the OPERATOR and the SYS
account passwords; the next card, however, was for MANAGER.SYS, and STREAMX
only prompted only for the MANAGER password.  Why?

Well, prompting for passwords is a good thing -- unless it's unnecessary.
You've already entered the SYS account password once; why prompt you for it
again? In fact, STREAMX's general rule is:

   * Whenever it's obvious that a user is authorized to log on with a
     particular logon, STREAMX won't even bother the user with a password
     prompt.

For instance, say that the NIGHTRUN job was submitted by MANAGER.SYS (or any
user with SM capability); the dialog would then look like this:

   :STREAM NIGHTRUN.SYSOP.SYS          --- This assumes that you've
                                           set our UDC that makes
                                           all :STREAM commands
                                           automatically run STREAMX

   STREAMX/3000  27Nymmdd  (c) VESOFT Inc, 1980  05:225

   JOB CARD = !JOB NIGHTRUN,OPERATOR.SYS; OUTCLASS=,1
   JOB CARD = *JOB DISCLEAN,JANITOR.SYS; OUTCLASS=,1
   JOB CARD = #JOB LOGDUMP,MGR.UTIL; OUTCLASS=,1
   JOB CARD = !JOB APJOB,DBA.AP,DATA; OUTCLASS=,1

     #J1723

The MANAGER.SYS user wasn't prompted for any passwords -- since he's the system
manager, he's obviously authorized to use any logon ID anywhere.  (This is
obviously true whenever he can use a :LISTUSER or :LISTACCT to figure out the
passwords; this is also true even when your system passwords are encrypted.)
STREAMX maximizes both your system security and your convenience.

Similarly, if OPERATOR.SYS was streaming the job, he wouldn't be prompted for
the OPERATOR or the SYS account passwords; if the account manager of the AP
account was streaming it, he wouldn't be prompted for any passwords in the AP
account.  This is particularly useful in two cases:

   * The system manager (or an account manager working in his own account)
     never needs to be bothered with passwords that he could easily figure out
     anyway; anything he streams will be automatically submitted.

   * An ordinary user (who typically submits jobs that log on as his own user
     ID) never needs to re-enter his own passwords, which he obviously had to
     know to log on in the first place.  This can be especially handy when a
     job is streamed from within a program (while the user might well be in
     block mode); the program can then submit the job through STREAMX without
     having to prompt the user for the password, insert it into a copy of the
     stream file, etc.

Allowing people to stream files without password prompts


NOPASS, STREAMX.DATA keyword ``passwords
$NOPASS, STREAMX.DATA keyword
we've been saying, STREAMX is quite intelligent in prompting you for job
card passwords.  It doesn't, for instance, prompt you for passwords at all if
you're the system manager -- after all, you must know them already (or can find
them out easily).  Similarly, if you're streaming a job stream that logs on as
your own user ID, you won't be prompted either, since you obviously know your
own passwords.

Let's say, however, that you want to allow your console operator to stream
certain jobs that log on as, say, MANAGER.SYS.  You're faced with a bit of a
dilemma:

   * You certainly don't want to tell your console operator the MANAGER.SYS
     password;

   * You don't want to embed the MANAGER.SYS passwords in the stream file (for
     the usual reasons -- it'll make the passwords hard to change, and will
     also require you to put some special security restrictions on the file to
     make sure that nobody can read it);

   * However, STREAMX won't automatically supply the passwords for you since
     OPERATOR.SYS doesn't have SM capability.

What you want to do is to set up a special exception to the normal security
rules -- you want to tell STREAMX

   "Whenever OPERATOR.SYS tries to stream this particular file, automatically
    insert the passwords without prompting him for them."

Naturally, STREAMX has such a mechanism (or else I wouldn't be telling you
about it).  In fact, we think it's a remarkably flexible mechanism at that.

You may, if you want to, build a file called STREAMX.DATA.VESOFT.  The file
might look something like this:

   :HELLO MANAGER.VESOFT
   :EDITOR
   /ADD
        1     $NOPASS   OPERATOR.SYS      @.JOB.SYS       @.@
        2     $NOPASS   OPER.PROD,PUB     J@.DATA.PROD    BATCH.PROD
        3     $NOPASS   JOE,@.@           @.@.DEV         @.DEV
        4     $NOPASS   JOE,@.@           X75.JOB.SYS     MANAGER.SYS
        5     //
   /KEEP STREAMX.DATA,UNN; EXIT

Note the way each line in this file is laid out:

   1. First, you say $NOPASS -- this means that you're telling STREAMX when not
      to prompt for passwords (in addition to the normal conditions when it
      won't prompt, e.g.  the user has SM).

   2.  Then, you specify

        The user ID of the user who is to be allowed to do the stream without
        password prompting.

      Note that this user ID can select by session name, user, account, and/or
      group, and can also use wildcards like @, # or ?.

   3.  Then, you indicate

        The files which can be streamed by the given user.

      After all, you don't want to allow OPERATOR.SYS to stream any file in the
      system -- he might just create himself a job that logs on as MANAGER.SYS
      and then lists all the system passwords!

      In the first line shown above, for instance, OPERATOR.SYS is only allowed
      to stream files that are kept in the JOB.SYS group, a group that he
      presumably has no WRITE or SAVE access to.

      This way, the system manager can build certain files in the JOB.SYS group
      and allow OPERATOR.SYS to stream those files without being prompted for
      passwords; however, all other files that OPERATOR.SYS streams will have
      normal security enforced on them (i.e.  the operator will be prompted for
      passwords as needed).

      Note that this parameter should be the actual filename of the file that
      contains any "!JOB", "!REMOTE HELLO", and/or ?$LOCKWORD=filename$?
      line(s).  For instance, if a job !STREAMs a file in another group or
      account, (and the user ID for that job has a password that the operator
      should not know), then this file must be included in this list as well.

   4.  Finally, you specify

        What logon ID the streamed job stream can log on as.

      For instance, the second $NOPASS line says

        "Automatically insert the passwords (without prompting) into any job
         stream

           that is streamed by the user OPER.PROD who is logged on into the PUB
             group;

           and, which is kept in the group DATA.PROD and whose name starts with
             J;

           and, which logs on as the user BATCH.PROD."

      If OPER.PROD,PUB tries streaming a file that isn't in DATA.PROD; or the
      name of which doesn't start with J; or logs on as anything other than
      BATCH.PROD, he will be prompted for passwords as usual.

As you see, we don't just say "OPERATOR.SYS can stream anything" or even
"OPER.PROD can stream any file that's kept in a particular group".  You can
thoroughly safeguard your system by restricting who does streaming, what is
being streamed, and where the streamed file logs on.

If any of the three selection criteria in the $NOPASS entry is not met, the
streamer will be prompted for passwords as usual.

One other feature relevant here is the ability to say something like:

   $NOPASS CAP=OP,AL @.JOB.SYS @.PROD

Note that instead of the "streaming user ID" pattern, we specified "CAP=OP,AL".
This line means that "any user who has both OP and AL capabilities may stream
-- without answering passwords -- any file in the JOB.SYS group that logs on
into the PROD account".  Thus, in addition to selecting by who is streaming a
file, you can also select by what capabilities the streaming user has.

Finally, a couple of miscellaneous points:


NOLOCK, STREAMX.DATA keyword ``lockwords
$NOLOCK, STREAMX.DATA keyword

  * When you say ?$LOCKWORD=filename$? in a job stream, STREAMX will prompt
     you for the given file's lockword (or automatically specify it if you have
     AM or SM capability).  You may also, after each $NOPASS entry in the file,
     specify a "$NOLOCK" followed by the mpefileset of files for which
     lockwords are not to be prompted.  Thus, if the STREAMX.DATA.VESOFT file
     looks like:

       $NOPASS JOE,@.@ @.@.DEV @.DEV $NOLOCK @.DATA.DEV-SECRET.DATA.DEV

     then any user who satisfies the $NOPASS selection criteria (i.e.  session
     name JOE, stream file in the DEV account, stream logon into the DEV
     account) will not be prompted for any lockwords for files in the DATA.DEV
     group except the file SECRET.DATA.DEV.  (Of course, lockwords will only be
     inserted in the job wherever you use the ?$LOCKWORD=filename$? construct
     in the job.) Similarly, if you have a line

       $NOPASS OPERATOR.SYS @.STREAM.SYS @.@ $NOLOCK @.@.@

     then OPERATOR.SYS streaming jobs from the group STREAM.SYS will not only
     not be prompted for any passwords but also won't be prompted for any
     lockwords.  If the $NOLOCK and the subsequent "@.@.@" were omitted, then
     OPERATOR.SYS would be prompted for file lockwords, even though the $NOPASS
     would prevent him from being prompted for passwords.

   * What happens if more than one $NOPASS applies to the same job? Normally,
     this doesn't matter since all it means is that there is more than one
     entry saying "stream this job without asking for passwords".  However, if
     one of the $NOPASS entries includes a $NOLOCK and the other(s) don't,
     STREAMX has to decide whether or not to prompt for lockwords when you say
     ?$LOCKWORD=filename$? in the job.  So, how does STREAMX decide?

     Just like LOGON does with SECURCON.DATA.VESOFT file, STREAMX will use the
     last $NOPASS that applies to the job and the streaming user.

     As in the SECURCON.DATA.VESOFT file, this can be quite useful.  For
     instance,

     $NOPASS  OPERATOR.SYS  @.JOB.@  CAP<>SM&CAP<>PM
     $NOPASS  OPERATOR.SYS  @.JOB.PRIV  CAP<>SM&CAP<>PM  $NOLOCK @.@.@

     means:

     1) OPERATOR.SYS will not be prompted for passwords when streaming any file
        in any group named JOB that does not log on as a user who has SM or PM
        capability and

     2) lockwords will be automatically supplied to jobs in the JOB.PRIV group
        that use the ?$LOCKWORD=filename$? construct.

   * If you use SECURITY's $BATCH-VEPROFILE keyword, STREAMX will normally
     prompt you for the SECURITY passwords of the job stream logon user as well
     as for his MPE passwords.  If $NOPASS is in effect, STREAMX will stream
     the job without prompting for either the SECURITY or MPE passwords.

   * The third parameter of $NOPASS -- the logon ID of the job -- may contain
     "!HPJOBNAME", "!HPUSER", "!HPACCOUNT", and/or "!HPGROUP", indicating the
     job/session name, user ID, account, and group (respectively) of the
     streaming user.  Thus the line

        $NOPASS  @.@  @.JOB.PROD  BATCH.!HPACCOUNT

     allows all users to stream (without being prompted for passwords) files in
     the JOB.PROD group that log on as the user BATCH in the streaming user's
     account.


STREAMX $NOPASS keyword and temporary files

  * When you build a temporary file, you can actually build it with any group
     and account (even ones that you normally don't have any access to) --
     thus, even a "plain vanilla" user can build a temporary file called
     XYZZY.PUB.SYS (although, of course, he can't save it).

     What if a user tries to fool STREAMX by building a temporary file which
     matches a $NOPASS mpefileset parameter? We can't let this be done, so
     whenever a temporary file is streamed, we pretend (for $NOPASS purposes)
     that its group and account are your logon group and account.

     Thus, if JOE.DEV,JOE tries to stream a temporary file called
     XYZZY.PUB.SYS, we'll treat that file (for $NOPASS purposes) just as if it
     were named XYZZY.JOE.DEV.


NOPASS and $LOGON-FORBID/$LOGON-PERMIT``permit`forbid
$NOPASS and $LOGON-FORBID/$LOGON-PERMIT

  * If you use the $LOGON-FORBID feature of the STREAMX.DATA file, then
     $NOPASS implies a $LOGON-PERMIT as well.  See the section Forbidding Some
     Job Submissions for more information.

   * Finally, if you don't build a STREAMX.DATA.VESOFT file at all, everything
     will still work all right -- users will be prompted for whatever passwords
     they ought to be (i.e.  those that they don't already know).  Creating a
     STREAMX.DATA.VESOFT file with $NOPASS records only defines exceptions to
     this rule -- users who are not prompted for passwords even though they
     would normally have to be.


Waiving stream file security ``contents
Waiving stream file security


NO-FILE-SEC-CHECK, STREAMX.DATA keyword ``FILE-SEC
$NO-FILE-SEC-CHECK, STREAMX.DATA keyword
as you may want to allow some people to stream some files for which they
don't know the !JOB card passwords, so you may want to let some people stream
files to which they normally wouldn't have read (or even execute) access.
STREAMX lets you do this using the STREAMX.DATA.VESOFT keyword
$NO-FILE-SEC-CHECK, e.g.

   $NO-FILE-SEC-CHECK  MGR.AP  @.APJOBS.PROD

which lets the user MGR.AP stream any jobs in the APJOBS.PROD group, even
though he normally wouldn't even have access to these files.  (Note that this
is a different matter from $NOPASS, which avoids password prompting when
streaming files that you otherwise do have access to; you may use both $NOPASS
and $NO-FILE-SEC-CHECK or either or neither.)


YES-FILE-SEC-CHECK, STREAMX.DATA keyword ``FILE-SEC
$YES-FILE-SEC-CHECK, STREAMX.DATA keyword
can have any number of $NO-FILE-SEC-CHECK records, as well as any number of
$YES-FILE-SEC-CHECK records, which can be used to specify exceptions to
preceding $NO-FILE-SEC-CHECKs.  For instance,

   $NO-FILE-SEC-CHECK   @.@     @.JOB.PROD
   $YES-FILE-SEC-CHECK  @.AP    GL@.JOB.PROD
   $NO-FILE-SEC-CHECK   MGR.AP  @.JOB.PROD-XX@.JOB.PROD

indicates that:

   * generally, any user can stream any file in @.JOB.PROD without regard for
     file security, but

   * users in the AP account will still have file security checks done for
     files in the set GL@.JOB.PROD, except that

   * the user MGR.AP will not have file security checks done for any file in
     @.JOB.PROD that doesn't start with XX.


Forbidding embedded passwords ``contents
Forbidding embedded passwords


EMBED-PASS-FORBID, STREAMX.DATA keyword ``forbid`passwords
$EMBED-PASS-FORBID, STREAMX.DATA keyword
we've discussed before, embedded passwords can be quite dangerous to your
system security because anybody who can read the job stream will see those
passwords.  The $EMBED-PASS-FORBID keyword of STREAMX.DATA.VESOFT lets you
forbid embedded passwords, either globally, e.g.

   $EMBED-PASS-FORBID   @.@   @.@.@   @.@

or for a particular userset, e.g.

   $EMBED-PASS-FORBID  @.AP  @.@.AP  @.@

(meaning here any jobs in the AP account [@.@.AP] streamed by an AP account
user [@.AP] that log on as any user ID [@.@]) or for everyone except for
particular users/jobs, e.g.


EMBED-PASS-PERMIT, STREAMX.DATA keyword ``streamx
$EMBED-PASS-PERMIT, STREAMX.DATA keyword

   $EMBED-PASS-FORBID   @.@           @.@.@       @.@
   $EMBED-PASS-PERMIT   @.@           @.JOB.SYS   @.@
   $EMBED-PASS-PERMIT   MANAGER.SYS   @.@.@       @.SYS

(meaning here that embedded passwords will only be permitted in jobs in the
JOB.SYS group and for jobs submitted by MANAGER.SYS that log on to the SYS
account).


DSLINE=, $EMBED-PASS-FORBID/-PERMIT option in STREAMX.DATA
format of the $EMBED-PASS-FORBID/-PERMIT keywords is the same as that of
the $NOPASS keyword -- streaming-userset, stream-file-fileset, and
job-stream-logon-userID-set.  You can also make these restrictions apply to
!REMOTE HELLO commands by specifying the job stream logon user ID with a
;DSLINE=xxx appended to it (just as you would for a $NOPASS).

Our VEAUDIT has several reports that show which jobs contain embedded
passwords; please see the VEAUDIT User Manual for details.


Forbidding some job submissions ``contents
Forbidding some job submissions

Sometimes, you may want to prohibit a particular set of users from submitting a
particular set of jobs or submitting jobs that log on to particular accounts,
even if the users know the appropriate passwords.  This can be particularly
useful if you use SECURITY passwords and $BATCH-VEPROFILE, in which case users
must go through STREAMX to submit jobs (since otherwise they'll be rejected by
SECURITY), and you can then really make these job submission restrictions work.


LOGON-FORBID, STREAMX.DATA keyword ``forbid
$LOGON-FORBID, STREAMX.DATA keyword
can restrict job submissions by adding $LOGON-FORBID lines to
STREAMX.DATA.VESOFT, e.g.

   $LOGON-FORBID  @.AP-MGR.AP  @.@.@  @.SYS

-- this would mean "forbid any users in the AP account, except for MGR.AP, from
streaming any jobs that log on to the SYS account".  Note that the format is
just like the format of the $NOPASS keyword -- the streaming userset, the job
stream mpefileset, and the job stream logon ID userset.


LOGON-PERMIT, STREAMX.DATA keyword``permit
$LOGON-PERMIT, STREAMX.DATA keyword
if you want to permit a particular userset to stream only a given subset
of the job streams you have prohibited? For this, you might say something like:

   $LOGON-FORBID  @.AP  @.@.@  @.@
   $LOGON-PERMIT  @.AP  MYJOB.DATA.AP  @.@
   $LOGON-PERMIT  @.AP  @.DATA.AP  @.AP
   $LOGON-FORBID  @.AP-MGR.AP  @.DATA.AP  MGR.AP

which would mean:

   * forbid anyone in the AP account from streaming anything, but

   * permit these users to stream the job MYJOB.DATA.AP, and

   * permit them to stream any jobs in the DATA.AP group so long as they log on
     to the AP account, but

   * in any event, forbid any AP user except for MGR.AP from streaming any
     DATA.AP files that log on as MGR.AP.

As you see, later $LOGON-FORBID/-PERMITs take precedence over earlier ones.


Implied $LOGON-PERMIT using $NOPASS in STREAMX.DATA``permit
Implied $LOGON-PERMIT using $NOPASS in STREAMX.DATA
also that a $NOPASS, in addition to its normal behavior, functions as a
$LOGON-PERMIT -- thus, if you say

   $LOGON-FORBID @.@ @.@.@ @.@
   $NOPASS ...
   $NOPASS ...
   $NOPASS ...
   $LOGON-PERMIT CAP=SM @.@.@ @.@

then job submissions will be completely forbidden except for those that are
specifically authorized by the $NOPASS lines and any jobs that are submitted by
users who have SM capability.  Note, of course, that the reverse is not true --
including a $LOGON-PERMIT will not automatically insert passwords for users
submitting jobs using STREAMX.


DSLINE=, $LOGON-FORBID/-PERMIT parameter in STREAMX.DATA
STARTSESS command and $LOGON-FORBID/-PERMIT in STREAMX.DATA

$LOGON-FORBID/-PERMIT actually apply not only to the job cards, but also to
!REMOTE HELLO lines (for which you'd append a ;DSLINE=xxx to the job logon
userset, just as you would for $NOPASS), and for any !STARTSESS commands in
your jobs.


Avoiding embedded lockwords ``contents
Avoiding embedded lockwords

Just as embedded MPE passwords are bad for your system security, so are
embedded file lockwords.  If you embed a lockword into a job stream, the
lockword will be readily visible to anybody who can read the file, and it'll
also be virtually impossible to change unless you're prepared to modify all the
job streams in which the lockword appears.

Now, MPE passwords appear in very well-defined places -- always in a !JOB card
or a !STARTSESS command -- but file lockwords can appear anywhere, in very many
MPE commands and even in input for programs.  Thus, it must be your
responsibility as creator of a STREAMX job stream to tell STREAMX where it can
expect to find filenames that might need lockwords inserted into them.

An example of this might be running the program QUERY.PUB.SYS, which you know
has a lockword on your system.  You'd say:

   !JOB QUERYRPT, ...
   !RUN ?$LOCKWORD=QUERY.PUB.SYS$?
   ...
   !EOJ

Instead of specifying the filename with its lockword -- e.g.
QUERY/SECRET.PUB.SYS -- you must say ?$LOCKWORD=filename$?.  When you stream
the job stream, STREAMX will either prompt you for the file's lockword or
automatically deduce it itself (if you're a system manager or an account
manager of the account in which the file exists).

For instance, if you're system manager and you stream the above job, you won't
be prompted for anything.  Rather, STREAMX will automatically substitute the
fully-qualified filename of QUERY.PUB.SYS (including the lockword), and the
resulting job stream would look like

   !JOB QUERYRPT, ...
   !RUN QUERY/SECRET.PUB.SYS
   ...
   !EOJ

On the other hand, if you're not a system manager, STREAMX will prompt you by
saying

   WHAT IS THE LOCKWORD OF THE FILE 'QUERY.PUB.SYS'?

Whatever the user enters (of course, echo is turned off on this prompt) will be
inserted as a lockword into the filename; if the user says "FOOBAR", then the
generated job stream would say

   !JOB QUERYRPT, ...
   !RUN QUERY/FOOBAR.PUB.SYS
   ...
   !EOJ

Also, recall that with the $NOPASS keyword in the STREAMX.DATA.VESOFT
configuration file you may specify that some passwords are to be automatically
supplied by STREAMX (without either prompting for them or making you embed
them).  Similarly, you might tell STREAMX to automatically supply some
lockwords, e.g.  if you want OPERATOR.SYS to stream some special MANAGER.SYS
job streams that run lockworded programs (but you want the lockwords to be
neither embedded in the job stream nor known to OPERATOR.SYS).  This is
accomplished with the $NOLOCK keyword, described above together with the
$NOPASS keyword.

Just as embedded MPE passwords seriously damage your MPE password security, so
embedded file lockwords substantially decrease the security provided by
lockwords.  STREAMX lets you avoid both embedded MPE passwords and file
lockwords.


Running STREAMX ``contents
Running STREAMX


Streaming a file with STREAMX
is, of course, just a program (not some kind of an operating system
patch).  However, we also provide a UDC that will run STREAMX whenever you want
to submit a job stream in the file STRMUDC.PUB.VESOFT.

This UDC emulates the MPE :STREAM command almost perfectly.  You can say

   :STREAM APJOB.PUB.AP

and it'll submit APJOB.PUB.AP (of course, prompting for passwords, taking care
of embedded questions, etc.); you can say

   :STREAM XJOB.TEST.DEV,*

and it will use STREAMX to stream XJOB.TEST.DEV with the "colon replacement
character" (which is by default set to "!", just like in MPE) set to "*".  The
only incompatibility is that MPE doesn't let us make UDCs be quite as flexible
as MPE commands; thus, when you use scheduling parameters, you should say

   :STREAM XJOB.TEST.DEV,*;"AT=22:00;DAY=FRI"


AT= MPE scheduling keyword, using it with STREAMX
DATE= MPE scheduling keyword, using it with STREAMX
DAY= MPE scheduling keyword, using it with STREAMX
IN= MPE scheduling keyword, using it with STREAMX
the scheduling parameters in quotes.  Also, the scheduling parameters
must be the third parameter, so if you don't have a colon replacement
character, you should say

   :STREAM XJOB.TEST.DEV,;"AT=22:00;DAY=FRI"

explicitly skipping the second parameter.


MPE/V and MPE/iX differences: STRMUDC.PUB.VESOFT ``STRMUDCX
MPE/V and MPE/iX differences: STRMUDC.PUB.VESOFT
STRMUDCX.PUB.VESOFT, the UDC file for MPE/iX
note for users of MPE/iX:


PARM=%1 to use :FILE STRMFILE=jobfile ``STREAMX
PARM=%1 to use :FILE STRMFILE=jobfile
UDC works by setting a :FILE equation for STRMFILE and then running the
STREAMX program with ;PARM=1.  However, by using the ANYPARM option of MPE/iX,
we can provide a UDC that exactly matches the syntax of the :STREAM command
(i.e.  you don't need to put quotes around any of the parameters).  This UDC is
provided in the file STRMUDCX.PUB.VESOFT.


PARM=%21 to suppress the STREAMX banner
PARM=%20 to suppress the STREAMX banner-interactive
PARM=%421 to suppress the STREAMX banner but not errors
Interactive mode of STREAMX
can also run STREAMX in so-called "interactive" mode.  Just say

   :RUN STREAMX.PUB.VESOFT

STREAMX will then prompt you for a filename and stream the file.  It'll keep
prompting you for filenames until you hit [RETURN]; then, it will terminate.
(As you see, the interactive/non-interactive mode is indicated by whether you
run STREAMX with ;PARM=1 [non-interactive] or without it [interactive].) If you
wish, you can run STREAMX with ";PARM=%20"  to suppress the STREAMX "banner"
(or ";PARM=%21" to both suppress the banner and run in non-interactive mode).
";PARM=%421" lets you suppress the banner but not the error messages.


Suspending STREAMX instead of terminating
fact, when you run STREAMX in this mode as a son process of another program
(e.g.  MPEX), STREAMX won't actually terminate but only suspend.  Then, the
next time you want to execute it, the program can (if it wants to) just
reactivate STREAMX instead of recreating it, which will be a lot faster.  Note,
however, that this requires a cooperating father process that knows about
STREAMX's suspension feature and can take advantage of it.


Access to stream files
normally requires either READ or EXECUTE access to the stream file
(unless you use the $NO-FILE-SEC-CHECK option in STREAMX.DATA, described under
Waiving Stream File Security above).  If you have a file that you want people
to stream but don't want them to read, you can take away READ access from it
and only allow EXECUTE access.  (However, since you no longer need to embed
passwords or lockwords in a stream file, you probably don't need this very
much).


CIERR 83, STREAMX asked to stream binary file ``ASCII
CIERR 83, STREAMX asked to stream binary file
STREAMXNOCHECKASCII, STREAMX JCW used to stream non-ASCII files

(NOTE: To avoid your accidentally trying to stream program files, USL files,
and the like, STREAMX will refuse to stream files that are of type binary
[except for QEDIT files].  If, for whatever reason, you want to stream a binary
file, you should do a :SETJCW STREAMXNOCHECKASCII = 1, which tells STREAMX that
it's OK to stream non-ASCII files.)

WHAT IF YOUR PROGRAM DOES A :STREAM PROGRAMMATICALLY

(USING THE COMMAND INTRINSIC?)


What if your program does a :STREAM programmatically ``contents
What if your program does a :STREAM programmatically


VECMMND procedure
:STREAM UDC is a very good way to make sure that you always run STREAMX
whenever you do a :STREAM.  Unfortunately, when you call the COMMAND intrinsic
to execute a command from a program, MPE doesn't check for UDCs; thus,
programmatic :STREAMs will execute the old, unimproved MPE :STREAM command.


MPE/V and MPE/iX differences: calling VECMMND
, we have ways (rather simple ways) for working around this problem --
one approach for Classic (pre-Spectrum) HP3000 programs and another for
Spectrum Native Mode programs.  (Since Compatibility Mode on Spectrums emulates
Classic HP3000 behavior, we use the Classic approach for Compatibility Mode
programs.)

"CLASSIC" AND/OR COMPATIBILITY MODE PROGRAMS


"CLASSIC" and/or compatibility mode programs ``contents
"CLASSIC" and/or compatibility mode programs

On Classic (MPE/V) computers (and for Compatibility Mode programs
on running on Spectrums), we have a procedure called VECMMND.  This procedure
is like the COMMAND intrinsic in all ways, except that if the command is a
STREAM command, it executes STREAMX instead of an MPE :STREAM.


VEPROC.JOB.VESOFT, installing VECMMND
procedure is kept in the USL file VEPROCU.PUB.VESOFT, and can be added to
the system SL by streaming the job stream VEPROC.JOB.VESOFT.  (It's a simple,
non-privileged procedure, so there's no problem adding it to the system SL --
just re-stream VEPROC.JOB.VESOFT whenever you do a system update.) Note: VEPROC
also adds the VEOPEN, VECHECKLOGON and MPEXHOOK procedures to the system SL.
See "Installing VEOPEN" in Database Security and "Checking SECURITY Logons From
Within Your Program" in Logon Security in this manual, and "MPEX HOOK" in the
chapter on Running MPEX of the MPEX User Manual for more details.

Once you've put VECMMND in the system SL (or in the group or account SL of the
group/account in which you keep the programs that will call VECMMND), you
should now change the program to call VECMMND instead of COMMAND.  This can be
done by patching existing object programs using the ,PATCH entry point.

By saying


PATCH, MAIN.PUB.VESOFT entry point ``patching`unpatching`streamx
PATCH, MAIN.PUB.VESOFT entry point

   :RUN MAIN.PUB.VESOFT,PATCH

you can patch any program to automatically use STREAMX instead of MPE :STREAM.
This is a perfectly harmless operation -- we just change the program's list of
"external references" (SL procedures that it calls) to make the program call
VECMMND instead of COMMAND.  It is exactly as if we changed the source code and
then recompiled it.

For instance, a typical patching sequence might be:

   :RUN MAIN.PUB.VESOFT,PATCH

   STREAMX/3000  27Nymmdd  (c) VESOFT Inc, 1980  05:225

   Enter program to be patched: EDITOR.PUB.SYS
   Program calls the COMMAND intrinsic.
   Change it to call (V)ecmmnd, (C)ommand or (N)o change at all? V

   *** Program has been patched ***

   END OF PROGRAM
   :
   :COMMENT  VECMMND must be in the system SL for this to work.
   :
   :EDITOR
   HP32201A.07.17 EDIT/3000 SUN, SEP 13, 1988,  2:21 PM
   (C) HEWLETT-PACKARD CO.  1985
   /:STREAM MYFILE
   (* now, STREAMX is automatically run from within EDITOR! *)
   /EXIT

As you can see, you can also use MAIN.PUB.VESOFT,PATCH to change a program that
calls VECMMND back to calling the COMMAND intrinsic.

You can even apply this patch to an entire fileset using MPEX's VECMDCH
(VE-CoMmanD-CHange) command:


VECMDCH, MPEX command to patch a fileset to use VECMMND

   :RUN MAIN.PUB.VESOFT
   %VECMDCH @.PUB.AP(ISCMPROG)

To switch a fileset from VECMMND back to COMMAND (should you ever want to do
this), add the option ";REMOVE" to the "%VECMDCH" command:


REMOVE, option for MPEX's VECMDCH command

   :RUN MAIN.PUB.VESOFT
   %VECMDCH @.PUB.AP(ISCMPROG); REMOVE

If you aren't an MPEX customer, the SECURITY tape that includes STREAMX has a
trial copy of MPEX, good for a month or so.  If it still hasn't expired, you
can :RUN MAIN.PUB.VESOFT and execute the above commands.  If it has expired,
you can still change your programs one by one.


CIERR 686, error returned by VECMMND if program lacks PH ``CIERROR
CIERR 686, error returned by VECMMND if program lacks PH
that any program that uses VECMMND must have PH capability.  When you
patch a program using :RUN MAIN.PUB.VESOFT,PATCH, we automatically give this
program PH; if you change your source code to call VECMMND, you should make
sure that you :PREP the program with ;CAP=PH.  If you do not do this, VECMMND
will return to you a CI error 686.

Also, regardless of whether you change the object or the source, the group and
account in which the program file resides will now need PH capability.  This
should be no problem since there's no harm in giving anybody PH capability.


SL segments, patching them to use STREAMX
note that you can use the same mechanism to also patch SL segments that
may use the COMMAND intrinsic to do :STREAMs.  If you specify an SL file name,
STREAMX will prompt you for the segment to be patched.  (If you do this, be
sure that all programs that call the patched SL procedure have CAP=PH -- you
can use MPEX's %ALTFILE...;CAP= command to give PH to any programs that don't
already have it.)

MPE/iX NATIVE MODE PROGRAMS


MPE/iX Native mode programs ``contents
MPE/iX Native mode programs
Calling STREAMX programmatically from MPE/iX programs

For Native Mode programs running on Spectrums, the solution is even simpler.

NATIVE MODE PROGRAMS THAT CALL THE HPCICOMMAND INTRINSIC


Native Mode programs that call the HPCICOMMAND intrinsic ``contents
Native Mode programs that call the HPCICOMMAND intrinsic

If the Native Mode program calls the HPCICOMMAND intrinsic, it will
"automatically" use STREAMX (assuming you have a STREAM UDC that runs STREAMX)
because HPCICOMMAND supports UDCs!  Reminder: on MPE/iX systems you should use
the STRMUDCX.PUB.VESOFT file rather than STRMUDC.PUB.VESOFT; it makes use of
features only available on MPE/iX to allow the STREAM UDC to be 100% compatible
with the MPE :STREAM command.

NATIVE MODE PROGRAMS THAT CALL THE COMMAND INTRINSIC


Native Mode programs that call the COMMAND intrinsic ``contents
Native Mode programs that call the COMMAND intrinsic

If the Native Mode program calls the COMMAND intrinsic, all you need to do is
to :LINK your program with ;CAP=PH and ;XL=STREAMNL.PUB.VESOFT.  For instance,
you might say:

   :LINK FROM=MYOBJ;TO=MYPROG;CAP=PH;XL="STREAMNL.PUB.VESOFT"

Whenever MYPROG would then try to call the COMMAND intrinsic, it will actually
call our own COMMAND procedure from STREAMNL.PUB.VESOFT.  This procedure will
invoke STREAMX if the command is a :STREAM command; if the command is not a
:STREAM command, it will execute it normally via the normal COMMAND intrinsic.

(Note that you still need to add the VECMMND segment to the Compatibility Mode
system SL using VEPROC.JOB.VESOFT, as discussed in the previous section.


QUIT with parameter -1041 when using VECMMND
you already have an older VECMMND segment in your system SL, you'll have to
delete it and add the new VECMMND segment from the VEPROCU.PUB.VESOFT file --
otherwise, you'll get an abort with PARM = -1041.)

What if you don't have the object file (pre-:LINK) of this program, but only
have the program file? No problem -- you should simply:

   * Make sure that the program has PH capability.  You can give it PH
     capability using VESOFT's MPEX:

       :RUN MAIN.PUB.VESOFT;INFO="ALTFILE GLPROG.PUB.GL;CAP=+PH"

     (Note that you must also make sure that the group and account in which the
     program reside have PH capability.)


STREAMNL.PUB.VESOFT, VECMMND NL file for MPE/iX``Spectrum
STREAMNL.PUB.VESOFT, VECMMND NL file for MPE/iX

  * :RUN the program with ;XL=STREAMNL.PUB.VESOFT, e.g.

           :RUN MYPROG;XL="STREAMNL.PUB.VESOFT"

You must specify the ;XL= parameter either on the :RUN or on the :LINK -- if
you omit it from both, your program will continue to call the standard COMMAND
intrinsic, which doesn't know anything about STREAMX.  No patching or source
code modifications are necessary.


STREAMNL, when running NM programs with ;LIB=
: in this case, it is quite likely that the program you are running was
supplied by another vendor.  Usually, this vendor will supply a UDC or command
file to start the program, and sometimes the existing UDC or command file
contains ;LIB=P or ;LIB=G on the run command.  If so, you must REMOVE the ;LIB=
and replace it with ;XL=XL.PUB.account,STREAMNL.PUB.VESOFT (for ;LIB=P) or
;XL=XL.group.acct,STREAMNL.PUB.VESOFT (for LIB=G).  (replace group and account
with the group and account where the program resides)

Finally, note that if you call the COMMAND intrinsic not from your main program
but from one of your XLs, you can still make the COMMAND intrinsic call know
about STREAMX.  Just be sure that you specify STREAMNL.PUB.VESOFT as the LAST
filename in the ;XL= list, e.g.

   :LINK FROM=MYOBJ;TO=MYPROG;XL="MYNLA,MYNLB,STREAMNL.PUB.VESOFT"


Building "smart" job streams ``contents
Building "smart" job streams

Prompting for passwords is only one part of STREAMX.  The other, very important
part is the ability to build "smart" job streams -- job streams that prompt the
user, job streams that do intelligent things based on the state of the
environment (which files exist, what day it is, etc.), and so on.  Let's look
at the example we showed in a previous section:

   ::ECHO YOU'RE STREAMING THE
   ::ECHO MASTER REPORT JOB STREAM
   ::IF HPDAY=1 or HPDAY=7 THEN
   ::  ECHO CAN'T DO THIS ON WEEKEND
   ::  EXIT
   ::ENDIF
   ::TELLOP MASTRPT BEING SUBMITTED
   !JOB MASTRPT,MANAGER.SYS
   !RUN MASTRPT.PUB.UTIL
   ?ENTER LIST FILENAME?
   TODAY-10
   ?$CINTEGER$MAX NUMBER OF FILES?
   !TELL HPUSER.HPACCOUNT DONE!
   !EOJ

What we see here is a standard job stream (the !JOB command, the !RUN, the
!EOJ, etc.) but with a number of special twists:

   * You can enter special STREAMX commands that start with "::" -- these
     commands will be executed as the job is being streamed.  They can be MPE
     commands (like ::IF, ::ENDIF, ::TELLOP, etc.), or special STREAMX commands
     (like ::ECHO, ::EXIT, ::PROMPT, ::ASSIGN, etc.).

   * You can indicate that the user is to be prompted for a certain value by
     enclosing the prompt string in "?" characters (e.g.  "?ENTER LIST
     FILENAME?").  At stream time, the streaming user will be prompted at his
     terminal, and the value he inputs will be inserted into the stream file in
     place of the question.  You can also specify various edit keywords, like
     CINTEGER (check to make sure the value input is an integer), NOECHO,
     DEFAULT, etc.

   * You can indicate that a certain expression is to be calculated and its
     result is to be inserted into the job stream.  For instance, when we said
     "TODAY-10", this meant "calculate the result of the expression 'today's
     date minus 10 days' and insert it into the job stream".  This expression
     might involve various operators and variables, such as TODAY, HPUSER and
     HPACCOUNT (which indicate the user and account name of the streaming
     user), variables representing values input by the user, and much more.

   * Finally, you can of course specify things that are to be left just as they
     are (such as the !JOB card, the !RUN command, etc.) -- anything not
     prefixed with "::", enclosed in "?"s or enclosed in "" characters is
     left alone.

PROMPTING FOR USER INPUT


Prompting for user input ``contents
Prompting for user input


Prompting: by STREAMX for user input, using ?xxx?
of the most useful features of STREAMX is its ability to prompt the user
for arbitrary input.  This way, if some piece of data (e.g.  the report date, a
data file name, etc.) is not known at the time you build the stream file but is
known to the user at the time he streams it, the user can be prompted for that
piece of data.  Thus, you can have flexible stream files that do different
things depending on user input.

The simplest example of such a stream file might be:

   !JOB MGR.AP, ?Which group should this job run in (DEV/PROD)?
   !FILE PROGLIST;DEV=LP,,?Number of report copies?
   !RUN AP010.PUB.AP
   ?Report option?
   !EOJ

Note the questions embedded in "?"s -- each of these will be asked of the user,
and his answer will be put into the job stream in place of the question.  Thus,
when this job is submitted using STREAMX, the conversation would look sort of
like this:

   STREAMX/3000  27Nymmdd  (c) VESOFT Inc, 1980  05:225

   Which group should this job run in (DEV/PROD)? PROD
   JOB CARD = !JOB MGR.AP,PROD
   Number of report copies? 2
   Report option? X7
     #J556

The job that is actually submitted -- the set of commands that MPE sees --
looks like this:

   !JOB MGR.AP,PROD
   !FILE PROGLIST;DEV=LP,,2
   !RUN AP010.PUB.AP
   X7
   !EOJ

Note that every place where there was a question in the original stream file,
the generated job stream now has the answer the user input in response to that
question.

INPUT OPTIONS


Input options ``contents
Input options

There are several valuable options available for the ? input construct.  For
instance, you can

   * Make sure that the value the user input is an integer by using the
     CINTEGER (Check INTEGER) option.

   * Make sure that the value the user input is a valid date by using the
     CDATEYMD, CDATEMDY or CDATEDMY option depending on what type of date you
     want.  (For more information on valid user date inputs, see the ::PROMPT
     Options -- Date Input chapter below.)

   * Prompt the user with echo turned off so that the user's input won't show
     up on the terminal.  This is done with the NOECHO option.

   * Specify the default value to be used if the user hits return.  This is
     done using the DEFAULT= option.

For example,

   !JOB MGR.DEV; OUTCLASS=,?$CINTEGER$Spool file output priority?
   !RUN MYPROG
   ?$DEFAULT="X7"$Report option (default X7)?
   ?$NOECHO$Database password?
   ?$NOECHO;CINTEGER$Secret number?
   ?$CDATEYMD$First report date (YY/MM/DD format)?
   ?$CDATEMDY;NOSLASH$Second report date (MM/DD/YY format)?
   !EOJ

will prompt for six things:

   - for the spool file output priority, which must be an integer (if the user
     types in a non-integer, an error message will be printed and he'll be
     prompted again);

   - for the report option -- if the user hits return, the default value "X7"
     will be used;

   - for the database password, which will be prompted for with echo off;

   - for the secret number, which will be prompted for with echo off and which
     must be an integer;

   - for the first report date, which must be a date in [YY]YY/MM/DD (either 2-
     or 4-digit year) format (e.g.  88/09/12 or 1988/09/12) -- this date will
     be written into the job stream file in YY/MM/DD format (with a 2-digit
     year);

   - and for the second report date, which must be a date in MM/DD/[YY]YY
     format, but will be written into the job stream file without slashes (i.e.
     in MMDDYY format, as in 092288).

Note how the desired options were enclosed in "$"s at the beginning of each
question; when several options were given, they were separated by ";"s.

This is only a small fraction of the ways in which you can prompt the user for
input.  You can also:

   - specify arbitrary checking conditions (e.g.  the input must be "A", "B" or
     "C");

   - save the value input by the user in a variable and then reuse the value
     later on;

   - make calculations based on user input;

   - and so on...

However, these options are available through a slightly different, more
sophisticated mechanism -- the ::PROMPT command, described below.  See the
documentation on that command for more information.

STREAMX COMMANDS THAT ARE EXECUTED

AT STREAM SUBMISSION TIME


STREAMX commands executed at stream submission time ``contents
STREAMX commands executed at stream submission time

The MPE :STREAM command takes a set of commands and makes a job stream out of
them.  All these commands are then executed inside that job at the time the job
is executing.  STREAMX, however, lets you specify certain commands that are to
be executed at the time the job is submitted.

DISPLAYING MESSAGES TO THE STREAMING USER (::ECHO)


Displaying messages to the STREAMing user (::ECHO) ``contents
Displaying messages to the STREAMing user (::ECHO)


::ECHO, STREAMX stream-time command
simplest command that you can execute at STREAM time is the ::ECHO command.
It simply displays a message to the user as the job is being submitted:

   ::ECHO   You are streaming the ARCHIVE job stream.
   ::ECHO   You will be prompted for the DBA.AP passwords;
   ::ECHO   if you should need to abort the job for any reason,
   ::ECHO   CALL THE OPERATOR at extension 374.
   ::ECHO
   !JOB ARCHIVE,DBA.AP; OUTCLASS=,1
   !RUN ARCHPROG.PUB
   ...
   !EOJ

When you stream the above job stream with STREAMX, you'll see the following:

   STREAMX/3000  27Nymmdd  (c) VESOFT Inc, 1980  05:225

   You are streaming the ARCHIVE job stream.
   You will be prompted for the DBA.AP passwords;
   if you should need to abort the job for any reason,
   CALL THE OPERATOR at extension 374.

   JOB CARD = !JOB ARCHIVE,DBA.AP; OUTCLASS=,1
   ENTER DBA USER PASSWORD:      (* echo is off for password input *)
   ENTER AP ACCOUNT PASSWORD:    (* echo is off for password input *)
     #J2317

The submitted job itself will never see the ::ECHO commands; all that it will
contain are the commands NOT PREFIXED WITH ::, i.e.:

   !JOB ARCHIVE,DBA.AP; OUTCLASS=,1
   !RUN ARCHPROG.PUB
   ...
   !EOJ

The ::ECHO command can be quite useful, especially in association with the
::PROMPT command described later; however, many even more useful commands are
also available.

STORING USER INPUT IN A VARIABLE (::PROMPT)


Storing user input in a variable ``contents
Storing user input in a variable


Prompting: by STREAMX for user input, using ::PROMPT
::PROMPT, STREAMX stream-time command
a previous section, we discussed how you can prompt a user for input using
the "?question?" construct.  This construct would ask the user for input and
replace the question in the job stream by the user's answer.  However, what if
you want to use the user's answer several times while only prompting for it
once?

The way to do this is with the ::PROMPT command which prompts the user for
input and then puts the input into a variable.  This variable can then be used
anywhere in the job stream (or any jobs that it streams), any number of times.
Here's an example (note that the "" and "" characters are curly braces; they
are not parentheses "()", angle brackets "<>" or square brackets "[]").

   ::PROMPT STRING PROG = "Program name"
   !JOB Cprog,TEST.AP; OUTCLASS=,1
   !COBOL prog.SOURCE, prog.USL
   !PREP prog.USL, prog.PUB
   !SAVE prog.PUB
   !TELLOP prog COMPILE DONE!
   !EOJ

The syntax of the ::PROMPT command is:

            STRING
   ::PROMPT INTEGER varname = "prompt"
            DATE

The first parameter (and it's required) is the type of the input you want to
get; it can be STRING, INTEGER or DATE.  Then you specify the variable name,
then an equal sign ("=") and then the prompt string, enclosed in quotes.

The user will see a prompt very much like the one he'd see for a "?question?"
construct:

   Program name? AP010

However, the user's input will not be inserted directly into the job stream
(since :: commands never appear in the generated job stream); rather, it'll be
stored in the string variable called PROG.  Then, whenever you want to insert
the value of the variable into the job stream, you just say

   PROG                (* UPPERCASE/lowercase *)

and the string "PROG" will be replaced by the actual variable value (this
very important "xxx" construct will be discussed in more detail in the
following sections).  Thus, the generated job stream would look like:

   !JOB CAP010,TEST.AP; OUTCLASS=,1
   !COBOL AP010.SOURCE, AP010.USL
   !PREP AP010.USL, AP010.PUB
   !SAVE AP010.PUB
   !TELLOP AP010 COMPILE DONE!
   !EOJ

As you recall, the "?question?" construct allowed you to specify special
options like NOECHO, DEFAULT=, CDATEYMD, CDATEMDY, and CDATEDMY that influenced
the way the input was handled.  The ::PROMPT command has all these features and
more.

::PROMPT OPTIONS -- DATE INPUT


::PROMPT options -- date input ``contents
::PROMPT options -- date input


Dates, in STREAMX
CDATEYMD, STREAMX input option
CDATEMDY, STREAMX input option
CDATEDMY, STREAMX input option
soon as STREAMX sees a command like

   ::PROMPT DATE REPORTDATE = "Enter report date"

it knows that the user's input must be checked to make sure that it's a valid
date.

By default, STREAMX expects the date input to be in [YY]YY/MM/DD (i.e.  either
2- or 4-digit year) format.  To input dates in MM/DD/[YY]YY format, you should
say:

   ::PROMPT DATE REPORTDATE = "Enter report date"; CDATEMDY

and for DD/MM/[YY]YY you should say

   ::PROMPT DATE REPORTDATE = "Enter report date"; CDATEDMY

(for completeness' sake, we encourage you to specify CDATEYMD for the default
[YY]YY/MM/DD format).

What can the user enter in response to the prompt? Well, he can enter a valid
date in the indicated format, with or without slashes, with either a 2- or 4-
digit year, e.g.  88/12/31, 1988/12/31, 881231 or 19881231 (for the default
[YY]YY/MM/DD format).  However, he can also enter several special sequences:

   *               Indicates today's date
   TODAY           Indicates today's date
   *+n             Indicates the date of the day n days after today
                   (e.g.  *+2 is the day after tomorrow's date)
   *-n             Indicates the date of the day n days before today
                   (e.g.  *-2 is the day before yesterday's date)
   TODAY+n         Same as *+n
   TODAY-n         Same as *-n

If a user enters one of the above, STREAMX will calculate the indicated date
and will store it in the specified variable.  Note that the same special
features are available in the "?$CDATExxx$question?" syntax (see above).

One thing that must be understood about date variables is that the format in
which the date variable was input is not remembered by STREAMX.  In other
words, if you enter a MM/DD/[YY]YY date with a CDATEMDY keyword or a
[YY]YY/MM/DD date with a CDATEYMD keyword, STREAMX will only remember the
actual value of the date, and not whether it was entered as MM/DD/[YY]YY or
[YY]YY/MM/DD.

What happens then when you say

   !RUN MYPROG;INFO="REPORTDATE"

in the job stream file? Well, STREAMX will replace the string "REPORTDATE"
with the value of the REPORTDATE variable in YY/MM/DD, 2-digit year format.
Even if REPORTDATE was input as a MM/DD/[YY]YY date, it'll be entered into the
job stream as a YY/MM/DD date.

What if you don't like this? What if you want to put the date into the job
stream as DD/MM/YY or MM/DD/YYYY or perhaps just YYMMDD without the slashes?

Well, the "xxx" syntax (which will be described in more detail later) does
not just mean "replace this with the value of the variable XXX".  It means
"replace this with the value of the EXPRESSION XXX".  The expression between
the "" and the "" might be just a simple variable, but it might also be
something else.

As we just mentioned, the full syntax of the "xxx" construct will be
discussed later; however, one of the things you can say with it is:

   CDATE(var,"format")

where FORMAT is one of the special date formatting strings described under
"Date Formatting" in the Output Formatting chapter of Appendix.  Here are a few
example formats to give you the idea (assuming REPORTDATE is 87/02/14):

   CDATE(REPORTDATE,'YY/MM/DD')   = 87/02/14
   CDATE(REPORTDATE,'MM/DD/YYYY') = 02/14/1987
   CDATE(REPORTDATE,'DD/MM/YY')   = 14/02/87
   CDATE(REPORTDATE,'YYMMDD')     = 870214
   CDATE(REPORTDATE,'DD.MM.YY')   = 14.02.87
   CDATE(REPORTDATE,'%W, %1M %0D, %4Y') =
     SAT, FEB 14, 1987

For instance, you can say

   !RUN MYPROG;INFO="CDATE(REPORTDATE,'YYMMDD')"

which STREAMX will (if REPORTDATE is 88/09/30) translate into

   !RUN MYPROG;INFO="880930"

If you say

   !RUN MYPROG;INFO="CDATE(REPORTDATE,'MM/DD/YY')"

then the line that STREAMX will generate in the job stream will read

   !RUN MYPROG;INFO="09/30/88"

Note that the "format" parameter in the CDATE construct (e.g.  "YYMMDD" or
'MM/DD/YY') must be enclosed in quotes; however, you can use either double
quotes (") or single quotes ('), whichever you wish.

::PROMPT OPTIONS -- CHECKING USER INPUT WITH AN ARBITRARY EXPRESSION


::PROMPT options -- arbitrary input checks ``contents
::PROMPT options -- arbitrary input checks


CHECK, STREAMX input option
CHECKERROR, STREAMX input option
you input a date with the ::PROMPT DATE command (whether or not you
specify a CDATEYMD/CDATEMDY/CDATEDMY keyword), the input is checked to make
sure it's a valid date.  When you input an integer with the ::PROMPT INTEGER
command, the input is checked to make sure it's a valid integer.

What if that's not enough? What if you want to make sure that the user inputs
the letter "A", "B" or "C"? Or a number between 1 and 10? Or the name of an
existing MPE file? STREAMX can let you check for this!

Let's say that you're inputting an integer and want to make sure that it's
greater than zero.  Here's how you'd do it:

   ::PROMPT INTEGER COPIES = "Number of copies"; CHECK=(COPIES>0)

The key thing here is, of course, the ;CHECK= option on the ::PROMPT command.
The CHECK= option specifies the LOGICAL EXPRESSION against which the input is
to be checked.  In this case, the expression is COPIES>0; if this expression
returns TRUE, all is well -- if this expression returns FALSE, an error message
("Error: Bad input") will be printed and the user will be prompted again until
he enters something valid.

Note the main components of the expression:

   - Variables, such as COPIES.  The variable being input and any variables
     that have already been input (or assigned) may be referred to.  For
     instance, you can say:

       ::PROMPT INTEGER LBOUND = "Lower bound"
       ::PROMPT INTEGER UBOUND = "Upper bound"; CHECK=(LBOUND<UBOUND)

     Some other predefined variables are also available to you (see Appendix
     for more details).

   - Constants: integer, date or string.  For instance, you can say:

       ::PROMPT DATE RPTDATE = "Date in 1988"; &
       ::            CHECK = (RPTDATE>=88/1/1 and RPTDATE<=88/12/31)

     (* note that the date constants 88/1/1 and 88/12/31 are both in YY/MM/DD
     format *)

       ::PROMPT STRING FLAG = "Type A or B"; &
       ::              CHECK = (FLAG="A" or FLAG="B")

   - Operators and functions.  These include =, <, >, +, -, AND, OR, TODAY,
     UPS, VEFINFO, etc.  -- all documented in Appendix.  For example:

       ::PROMPT DATE D = "Date, no more than 10 days after today"; &
       ::                CHECK = (D<=TODAY+10)


Checking STREAMX input: for file existence

      ::PROMPT STRING SRC = "Source file"; CHECK=(FEXISTS(SRC))

    (* note that FEXISTS(X) returns TRUE if the file indicated by X exists *)


Checking STREAMX input: for file size

      ::PROMPT STRING F = "Data file"; &
       ::       CHECK=(VEFINFO(F).EOF<=VEFINFO(F).FLIMIT-100)

    (* the check expression is TRUE if there's room for at least 100 records
    left in the file *)

     See Appendix for many more very useful functions that can be used in the
     CHECK= keyword.

Another keyword that goes hand in hand with CHECK= is CHECKERROR=.  By default,
if the CHECK= expression returns FALSE, STREAMX prints the message "Error: Bad
input" and re-prompts the user.  CHECKERROR= lets you specify your own error
message, e.g.:

   ::PROMPT STRING SRC = "Source file"; CHECK = (FEXISTS(SRC)); &
   ::              CHECKERROR = "Error: No such file!"

   ::PROMPT INTEGER PRI = "Output priority (1 to 10)"; &
   ::               CHECK = (BETWEEN(PRI,1,10)); &
   ::               CHECKERROR = "Expected a number from 1 to 10"

As a general rule, we think you'll want to specify CHECKERROR= almost every
time you use CHECK=.

Finally, a couple of other useful CHECK= expressions:


Yes/no input

  ::PROMPT STRING ANS = "Answer (Y or N)"; &
   ::              CHECK = (UPS(ANS)="Y" or UPS(ANS)="N")

                   (* UPS(X) upshifts the string X *)


Checking STREAMX input: for file existence

  ::PROMPT STRING MODULE = "Module name"; &
   ::              CHECK = (FEXISTS("S"+MODULE+".SOURCE.AP")); &
   ::              CHECKERROR = "S"+MODULE+".SOURCE.AP doesn't exist!"

                   (* + can be used to concatenate strings; CHECKERROR can take
                      not just a constant string, but also any string
                      expression *)

::PROMPT OPTIONS -- NOECHO AND DEFAULT


::PROMPT options -- NOECHO and DEFAULT ``contents
::PROMPT options -- NOECHO and DEFAULT


NOECHO, STREAMX input option ``echo
NOECHO, STREAMX input option
DEFAULT, STREAMX input option
like the "?question?" syntax lets you specify the NOECHO and DEFAULT=
keywords, so does the ::PROMPT command.  For instance, saying

   ::PROMPT STRING IMAGEPASSWORD = "Image password for MYDB"; NOECHO

will prompt for IMAGEPASSWORD with echo turned off; saying

   ::PROMPT STRING GROUP = "Group (default PUB)"; DEFAULT = "PUB"

The syntaxes of the keywords are, as you see, the same -- either NOECHO or
DEFAULT="string" (the string must be enclosed in quotes, either single or
double).  Note that the DEFAULT= string must be a string constant, never a
variable or an expression.

::ASSIGN COMMAND


Assigning values to variables (::ASSIGN) ``contents
Assigning values to variables (::ASSIGN)


::ASSIGN, STREAMX stream-time command
::PROMPT command lets you input variables from the user.  What if you just
want to set a variable to some value or expression?

For instance, let's say that you're inputting a string and want that string
upshifted.  To do this, you might say:

   !JOB MYJOB,MGR.PROD; OUTCLASS=,1
   ::PROMPT STRING K = "Key value"
   ::ASSIGN K = UPS(K)
   !RUN MYPROG1
   K
   !RUN MYPROG2
   K
   !EOJ

The ::PROMPT statement inputs a string value for the variable K; the ::ASSIGN
statement sets K to the result of the expression UPS(K).  UPS (see Appendix for
more info) is a function that takes a string and upshifts it -- after the
::ASSIGN, K contains the upshifted input value.  When K is substituted into the
job stream with the "K" construct, the value that's substituted is the new,
upshifted value of K.

Note that you could have, of course, written this job stream as

   !JOB MYJOB,MGR.PROD; OUTCLASS=,1
   ::PROMPT STRING K = "Key value"
   !RUN MYPROG1
   UPS(K)
   !RUN MYPROG2
   UPS(K)
   !EOJ

This would have kept K as the non-upshifted value, but upshifted it at the time
it was substituted into the job stream.  In this case, the ::ASSIGN is just a
convenience -- if you referred to K ten times in the job stream, you probably
wouldn't want to have to remember to say "UPS(K)" every time you used it.

::ASSIGN is particularly useful when you use the ::IF and ::WHILE commands
(more about them below).  For instance, you might say:

   ::PROMPT STRING ANS = "Do you want to run in production (Y/N)"; &
   ::                    CHECK=(UPS(ANS)='Y' or UPS(ANS)='N')
   ::IF UPS(ANS)='Y' THEN
   ::  ASSIGN GROUP = "PROD"
   ::ELSE
   ::  ASSIGN GROUP = "DEV"
   ::ENDIF
   !JOB BATCH.AP,GROUP; OUTCLASS=,1
   !RUN MYPROG.GROUP.GL
   ...
   !EOJ

Here, the user was prompted for a Y/N answer (note how the CHECK= option on the
::PROMPT made sure he did enter a Y or N).  The ::IF statement (discussed in
more detail later) checks the answer that was entered, and depending on its
value (Y or N) sets the variable GROUP to either "PROD" or "DEV".  Similarly,
in a ::WHILE loop (again, discussed in more detail below), you might say:

   !JOB AP010,MGR.AP,PROD; OUTCLASS=,1
   !COMMENT   AP010 PROMPTS FOR SEVERAL KEY VALUES (UNTIL A "//"
   !COMMENT   IS SEEN) AND PRINTS INFORMATION ABOUT THEM.
   !RUN AP010
   ::ASSIGN KEYVAL = " "
   ::WHILE KEYVAL <> "//"
   ::  PROMPT STRING KEYVAL = "Key value or // to exit"
   KEYVAL
   ::ENDWHILE
   !EOJ


Conditional processing with ::IF/::ELSEIF/::ELSE``contents
Conditional processing with ::IF/::ELSEIF/::ELSE


::IF/::ELSEIF/::ELSE, STREAMX stream-time command
example we gave above shows a good use of the conditional processing
commands -- ::IF, ::ELSEIF, ::ELSE, and ::ENDIF; we want to -- depending on the
user's input -- execute one of two ::ASSIGN statements.  The
::IF/::ELSEIF/::ELSE/::ENDIF construct is, of course, much like MPE's :IF,
:ELSEIF, :ELSE and :ENDIF commands (except, of course, that MPE doesn't handle
strings, have a UPS function, etc.).  If UPS(ANS)='Y' (i.e.  the upshifted ANS
string is equal to 'Y') then the statements between ::IF and ::ELSE are
executed; otherwise, the statements between ::ELSE and ::ENDIF are executed.

Another example of this might be something like:

   ::IF HPDAY=1 or HPDAY=7 THEN
   ::  COMMENT SUNDAY or SATURDAY
   ::  ASSIGN MODE = "WEEKEND"
   ::ELSE
   ::  ASSIGN MODE = "WEEKDAY"
   ::ENDIF

Here the variable MODE is set to "WEEKEND" if the current day is Sunday or
Saturday and to "WEEKDAY" otherwise.

However, the ::IF construct is not only used to select STREAMX commands to be
executed.  You can also select which lines are to be included into the job
stream.  For instance, you might say:

   !JOB NIGHTRUN,MGR.PAYROLL; OUTCLASS=,1
   ::PROMPT STRING INC = "Include data roll-over (Y/N)"; &
   ::              CHECK = (UPS(INC)='Y' or UPS(INC)='N')
   ::IF UPS(INC)='Y' THEN
   !PURGE DATA777.PUB
   !RENAME DATA777.NEW, DATA777.PUB
   !RUN ROLLPROG
   ::ENDIF
   !RUN NIGHT1.PROG;LIB=G
   !RUN NIGHT2.PROG;LIB=G
   !EOJ

Here, a user is prompted for a Y/N answer; if he says Y, the text between
!PURGE and !RUN is included into the job stream -- if he says N, the text is
not included.  Thus, this file can generate one of two possible job streams:

   (If user answers 'Y')
   !JOB NIGHTRUN,MGR.PAYROLL; OUTCLASS=,1
   !PURGE DATA777.PUB
   !RENAME DATA777.NEW, DATA777.PUB
   !RUN ROLLPROG
   !RUN NIGHT1.PROG;LIB=G
   !RUN NIGHT2.PROG;LIB=G
   !EOJ

or

   (If user answers 'N')
   !JOB NIGHTRUN,MGR.PAYROLL; OUTCLASS=,1
   !RUN NIGHT1.PROG;LIB=G
   !RUN NIGHT2.PROG;LIB=G
   !EOJ

As you see, depending on a condition -- which in this case involved a variable
input by the user, but which might also involve the day of week, the user or
account name of the streaming user (HPUSER or HPACCOUNT), etc.  -- we could
either include or exclude a certain set of commands from the generated job
stream.

Of course, if a set of commands is excluded using an ::IF, any questions
("?xxx?") embedded in those excluded commands are not asked.  Everything in a
portion of the stream excluded with an ::IF is completely ignored.


STREAMXIFMISMATCHOK, STREAMX JCW ``if`mismatch
STREAMXIFMISMATCHOK, STREAMX JCW
happens if the ::IFs and ::ENDIFs don't match? Earlier versions of STREAMX
allowed this; however, we now consider this an error.  If STREAMX reaches the
end of the job and doesn't find a matching ::ENDIF for every ::IF, it prints an
error message and does not submit the job.  If you have jobs that count on the
"feature" which allowed unmatched ::IF/::ENDIF pairs, simply do a

   :SETJCW STREAMXIFMISMATCHOK = 1

before streaming the job and STREAMX will behave the "old" way.

ITERATIVE PROCESSING WITH THE ::WHILE COMMAND


Iterative processing with the ::WHILE command ``contents
Iterative processing with the ::WHILE command


::WHILE, STREAMX stream-time command
's say your program prompts you for several key values, expecting a "//" to
terminate input.  Now, when you run your program from a job stream, you'd like
STREAMX to prompt the user for the key values -- however many he wants -- to be
passed to the program.

Obviously, ordinary STREAMX ::PROMPTs and variable substitution don't quite do
the trick here, and the ::IF/::ELSE/::ENDIF construct doesn't help, either.
What you really need is a looping construct, and that's exactly what STREAMX
gives you with ::WHILE/::ENDWHILE.

In fact, the problem mentioned above can easily be solved as follows:

   !JOB KEYRPT,USER.AP; OUTCLASS=,1
   !RUN KEYRPT.PUB;LIB=P
   ::PROMPT STRING KEYVAL = "Enter key value (or // to exit)"
   ::WHILE KEYVAL<>"//"
   KEYVAL
   ::  PROMPT STRING KEYVAL = "Enter key value (or // to exit)"
   ::ENDWHILE
   //
   !EOJ

How does this work? Well, the first two lines (the !JOB and the !RUN) are, of
course, copied directly to the job stream.  Then, the user is prompted for
KEYVAL.  This key value is used in the ::WHILE loop -- the loop only continues
while KEYVAL is not equal to "//".

Now, as long as KEYVAL <> "//", the body of the loop -- all the lines from the
::WHILE to the ::ENDWHILE -- are executed repeatedly.  The "KEYVAL" line
simply says "include the current value of KEYVAL into the job stream"; this is
simple variable substitution.  The ::PROMPT line prompts for the new value of
KEYVAL; control then returns back to the ::WHILE statement, which checks
whether or not KEYVAL is "//", and if it isn't, continues executing the loop.

When the loop is done -- when all the key values have been prompted for and
included into the job stream, and when the user terminates the loop by entering
"//" -- the last two lines in the job stream are executed.  These two lines
simply add a "//" and an "!EOJ" to the generated job.  Note that the ::WHILE
loop did not actually include the "//" into the job, since when the user
entered "//", the ::WHILE loop immediately terminated before the "KEYVAL"
line got a chance to be executed again.

Practically speaking, when you use STREAMX to submit this job, here's what the
conversation would look like:

   STREAMX/3000  27Nymmdd  (c) VESOFT Inc, 1980  05:225

   JOB CARD = !JOB KEYRPT,USER.AP; OUTCLASS=,1
   Enter key value (or // to exit)? JONES
   Enter key value (or // to exit)? SMYTHE
   Enter key value (or // to exit)? NATHAR
   Enter key value (or // to exit)? //
     #J558

and here's what the generated job would look like:

   !JOB KEYRPT,USER.AP; OUTCLASS=,1
   !RUN KEYRPT.PUB;LIB=P
   JONES
   SMYTHE
   NATHAR
   //
   !EOJ

Another example of such a ::WHILE loop might be this:

   !JOB QUERYRPT,MGR.PROD,DATA; OUTCLASS=,1
   !RUN QUERY.PUB.SYS
   BASE=MYBASE
   ?$NOECHO$MYBASE password?
   5
   ::ECHO Enter the QUERY >FIND condition now (terminate lines with
   ::ECHO an & for continuation):
   ::PROMPT STRING COND = "Condition"
   FIND COND
   ::WHILE COND[LEN(COND)-1:1]="&"
   ::  PROMPT STRING COND = "Condition"
        COND
   ::ENDWHILE
   XEQ RPTFILE
   EXIT
   !EOJ

The central thing here is the prompt for the QUERY >FIND condition, which might
be continued from line to line by terminating each to-be-continued line with a
"&" (exactly the way you'd do it in QUERY itself).  The user is prompted for
the first line of the >FIND condition; if the last character in the user's
input is "&", he's prompted again, and again until he enters a line that is not
terminated with a "&".  Note the ::WHILE loop expression:

   ::WHILE COND[LEN(COND)-1:1]="&"

LEN(COND), of course, returns the length (in characters) of the string COND;
the construct COND[START:NUMCHARS] returns NUMCHARS characters of COND starting
with character #START (where the first character of COND is considered
character #0).  Thus, COND[LEN(COND)-1:1] means

   "one character of COND starting at character number LEN(COND)-1"

which simply means the last character of COND.

Again, an example of the practical effects of the job stream we just showed:

   STREAMX/3000  27Nymmdd  (c) VESOFT Inc, 1980  05:225

   JOB CARD = !JOB QUERYRPT,MGR.PROD,DATA; OUTCLASS=,1
   MYBASE password?                    (* no echo on input *)
   Enter the QUERY >FIND condition now (terminate lines with
   an & for continuation):
   Condition? STATE="CA" or STATE="NY" or STATE="TX" &
   Condition? OR COUNTRY="CANADA" or PRICE>1500 or &
   Condition? STATUS="Z7"
     #J423

The generated job stream looks like:

   !JOB QUERYRPT,MGR.PROD,DATA; OUTCLASS=,1
   !RUN QUERY.PUB.SYS
   BASE=MYBASE
   MYPASS
   5
   FIND STATE="CA" or STATE="NY" or STATE="TX" &
        or COUNTRY="CANADA" or PRICE>1500 or &
        STATUS="Z7"
   XEQ RPTFILE
   EXIT
   !EOJ

Finally, one more example -- let's say that for test purposes, you need to
build 50 files with names from X1 to X50.  Again, a ::WHILE loop would do the
trick:

   !JOB FTEST,JOHN.DEV; OUTCLASS=,1
   ::ASSIGN I = 1
   ::WHILE I <= 50
   !BUILD XI;REC=-80,,F,ASCII
   ::  ASSIGN I = I+1
   ::ENDWHILE
   !RUN FILETEST.TEST;PARM=7
   !EOJ

Very simple -- I is set to 1, and then the !BUILD and the ::ASSIGN are executed
until I is 50.

EXECUTING ARBITRARY MPE COMMANDS AT STREAM TIME


Executing arbitrary MPE commands at stream time ``contents
Executing arbitrary MPE commands at stream time


MPE commands, executing them at stream time using ::
thing that the :: construct is good for is for executing arbitrary MPE
commands at stream time.  For instance, you might say:

   ::TELLOP  ROLLOVER job submitted by HPUSER.HPACCOUNT!!!
   ...

Here the :TELLOP command is executed (as a normal MPE command) at the time
STREAMX is processing the job (not at the time the job is executing).  In this
case, it might be that the job is normally submitted with scheduling parameters
(e.g.  AT= or IN=); however, the message will be sent to the console at the
time the user submits the job stream, even though the job may not start up for
hours or days.  Note how the MPE command can contain a "xxx" construct that
will evaluate the expression "xxx" and substitute its value into the :TELLOP
before the command is actually executed.


::COMMENT, STREAMX stream-time command
Comments inside job streams
commands (:BUILD, :PURGE, :RUN, etc.) can be executed too.  For instance,
you'll find that some of the examples given earlier used the command
"::COMMENT" -- this is not a special STREAMX command, but rather a special case
of STREAMX's ability to execute arbitrary MPE commands (in this case :COMMENT).


Executing arbitrary MPEX commands at stream time


MPEX commands, executing them at stream time using ::%
you are an MPEX user, you can execute arbitrary MPEX commands at stream time
by preceding them with ::%.  For example, you might say something like

   ::IF VEFINFO("DATAFILE").OPENED THEN
   ::    ECHO The file DATAFILE is in use!!!
   ::    ECHO Here are the jobs/sessions that have it open:
   ::%   LISTF DATAFILE,ACCESS
   ::    ECHO Get them out, and re-submit the job.
   ::    EXIT
   ::ENDIF

Note: you can't (directly) use multi-line MPEX commands like
%REPEAT...%FORFILES.  Instead, you should use MPEX's %MANY and/or %XEQ commands
(see the MPEX User Manual for details).


STRMXMGR files
executing the first ::% command, STREAMX will execute the commands in
the file STRMXMGR.PUB.VESOFT (similar to MPEXMGR.PUB.VESOFT).  If
STRMXMGR.PUB.VESOFT contains an INITMPEXMGR command, it will also execute the
commands in STRMXMGR.PUB.logonaccount and STRMXMGR.logongroup.logonaccount.

CANCELLING THE SUBMISSION OF A JOB STREAM (::EXIT)


Cancelling the submission of a job stream (::EXIT) ``contents
Cancelling the submission of a job stream (::EXIT)


::EXIT, STREAMX stream-time command
Aborting job stream submission
Cancelling job stream submission
Stopping job stream submission
-- especially when you use ::IF statements -- you may want to cancel
the submission of a job stream.

For instance, say that a job stream can't execute if a particular file doesn't
exist.  At STREAMX time, you'd like to check for the existence of the file, and
if it isn't there, print a message and cancel the job stream submission
altogether.

You can do this by saying something like the following:

   !JOB X137A,MANAGER.PROD,DB; OUTCLASS=,1
   ::IF NOT FEXISTS('MAININDX.DB.PROD') THEN
   ::  ECHO Error!  The MAININDX.DB.PROD file doesn't exist!
   ::  EXIT
   ::ENDIF
   ...

If the MAININDX.DB.PROD file doesn't exist, the statements between ::IF and
::ENDIF will be executed; the ::ECHO will print an error message, and the
::EXIT will prevent the job from being executed.

If you had omitted the ::EXIT, the message would still be printed, but STREAMX
would continue processing the job stream and would eventually submit the job.

COPYING A SESSION'S :FILE-equations TO A JOB (::SAVEFILEEQ)


Copying a session's :FILE-equations to a job (::SAVEFILEEQ) ``contents
Copying a session's :FILE-equations to a job (::SAVEFILEEQ)


::SAVEFILEEQ, STREAMX stream-time command
you have a job that runs a program that reads a bunch of files.
Sometimes, you want to issue :FILE-equations to have this program read
different files (perhaps for testing or to re-run a report on old data).  In a
session, you simply enter the :FILE commands, and then run the program.  (MPEX
automatically copies the :FILE commands to jobs submitted via it's "$" prefix
and %SUBMIT and %SCHEDULE commands!) To do the same thing in batch, you would
normally have to either edit the job file (changing and/or inserting the :FILE
commands), save the job under a different name (so you don't "wipe out" the
production copy), and :STREAM the new job.

With STREAMX you could, of course, use ::PROMPT to ask for the filenames every
time you :STREAM the job, but there is a shortcut.

The ::SAVEFILEEQ command (it doesn't have any parameters) copies all of the
:FILE-equations you currently have set in your session to the job you are
submitting (at the point in the job where the ::SAVEFILEEQ command is).

For example, suppose the job MONTHEND.JOB.PR looks like this:

   !JOB MONTHEND,REPORT.PR
   !FILE DATAFILE=CURRENT.DATA.PR
   ::SAVEFILEEQ
   !RUN MONTHEND.PUB.PR
   !EOJ

To run this job using a different data file, you would enter the following
commands in your session  (assuming you are using our UDC, that makes the
:STREAM command automatically run STREAMX):

   :FILE DATAFILE=JANUARY.DATA.PR
   :STREAM MONTHEND.JOB
   :RESET DATAFILE

That's all there is to it!

FORCING FIXED-LENGTH JOB STREAM RECORDS (::SETFIXED)


Forcing fixed-length job stream records (::SETFIXED) ``contents
Forcing fixed-length job stream records (::SETFIXED)


::SETFIXED, STREAMX stream-time command ``::SETVARIABLE
::SETFIXED, STREAMX stream-time command
, STREAMX views all the data in the file being streamed -- including
trailing blanks, if any -- as data that is to be copied into the job stream
that actually gets submitted.  Thus, if an input line contains "!SHOWTIME"
followed by 71 blanks, the generated job stream will also contain "!SHOWTIME"
followed by 71 blanks.

What if the file being streamed is a variable record length file (or $STDIN or
a QEDIT file)? These files do not include trailing blanks, so STREAMX will not
include trailing blanks in the generated job stream.  Similarly, if an input
line contains the text "!BUILD MYFILE" followed by 65 blanks (a total input
length of 80 characters), and the text "MYFILE" gets replaced by the contents
of the variable "MYFILE" (for instance, "XYZ"), then the generated line will
contain the text "!BUILD XYZ" followed by 65 blanks.

In general, this is pretty much what you want.  All the data from the input
file, including trailing blanks, gets copied to the generated job stream; and,
in any case, whether or not there are trailing blanks should be irrelevant to
any programs that are run in the job.

Unfortunately, some programs do care about how many trailing blanks they get.
Many programs that are designed to run in session mode (in which trailing
blanks usually do not appear) can't handle trailing blanks at all; for
instance, they may expect the input to be 8 characters or less, and complain if
they get an input line of, say, 80 characters (even if the last 72 of them are
blanks).  For these programs, we recommend that you keep your job stream as a
variable record length file, so that the job stream (and thus the
STREAMX-generated job) will not have any trailing blanks.

Other programs, however, insist on getting trailing blanks! For some reason,
they seem to dislike input lines that are less than, say, 72 or 80 characters
long.  (This appears to happen for some programs that are written in COBOL and
use standard COBOL I/O.)

Thus, you must guarantee that these programs get all the trailing blanks they
need.  It might seem that it would be enough to make the input file have
fixed-length records, but there's still the problem of records (such as "!BUILD
MYFILE" followed by 65 blanks) that get shorter when xxx and ?xxx?
substitution takes place.  To make sure that the file has trailing blanks even
after this substitution, just add a line that says

   ::SETFIXED

to the very start of your job stream.

If you want to, you can set this as the default by saying


STREAMXSETFIXED, STREAMX JCW used to make ::SETFIXED default

  :SETJCW STREAMXSETFIXED = 1


::SETVARIABLE, STREAMX stream-time command ``::SETFIXED
::SETVARIABLE, STREAMX stream-time command
your session before running STREAMX to submit the job.  By putting this
:SETJCW into your system-wide logon UDC, you can even make this the system
default; if you do this, you can still make a stream be submitted in the
default way described above by putting in a ::SETVARIABLE command.


STREAMXSETFIXEDRECSIZE, STREAMX JCW to set record length
can control the record size of the fixed-record-length job created by
STREAMX by using the STREAMXSETFIXEDRECSIZE JCW (the default is 255).  Thus, to
submit a fixed-length, 80-byte record job through STREAMX, simply say

   :SETJCW STREAMXSETFIXED = 1
   :SETJCW STREAMXSETFIXEDRECSIZE = 80

before running STREAMX.

EXECUTING STREAMX COMMANDS FROM ANOTHER FILE WITH THE ::USE COMMAND


Executing STREAMX commands from another file (::USE) ``contents
Executing STREAMX commands from another file (::USE)


::USE, STREAMX stream-time command
you might have a STREAMX "procedure" that you may want to use in
several job streams -- several STREAMX commands that do some useful task (e.g.
initialize some default variables, prompt for a commonly-used input value,
etc.) that can be useful in many places.

For example, you may want to have a sequence of commands that prompts for a
variable:

   ::PROMPT STRING CUSTNUM = "Enter customer number"; &
   ::       CHECK = (CUSTNUM = "BOFA" or CUSTNUM = "AT&T" or &
   ::                CUSTNUM MATCHES "HP@" or CUSTNUM = "ACME" or &
   ::                CUSTNUM MATCHES "???###"); &
   ::       CHECKERROR = "Must match standard naming convention"
   ::IF BETWEEN(STR(CUSTNUM,4,1),"0","9") THEN
   ::  COMMENT One of the ???### customers
   ::  ASSIGN CUSTNUMA = STR(CUSTNUM,1,3)
   ::  ASSIGN CUSTNUMB = STR(CUSTNUM,4,3)
   ::ELSE
   ::  COMMENT One of the special names
   ::  ASSIGN CUSTNUMA = CUSTNUM
   ::  ASSIGN CUSTNUMB = ""
   ::ENDIF

You may need to do these commands in dozens of different jobs, but you don't
want to include them into each job (since this would be inconvenient and
unmaintainable).  Instead, you can put them into a file (let's call it
CUSTUSE.JOB.PROD) and just say

   ::USE CUSTUSE.JOB.PROD

in any job stream from which you need to execute those commands.  The effect
will be the same as if the commands had actually been a part of the ::USEing
job stream.

This will work not just for :: commands, but also for non-:: lines which
STREAMX will (as usual) write to the job stream file.  Say that many of your
job streams need to have a particular set of !FILE equations inside them --
instead of including them into each job stream, you can build a file called
FILEUSE.JOB.PROD that contains

   !FILE BASEAP=BASEAP.DATA
   !FILE CONFFILE=CONF1.DATA
   !FILE RPT;DEV=LP,1,1
   !FILE FTN01=LOGFILE.DATA,NEW;SAVE

and then have your job stream say

   !JOB ...
   ::USE FILEUSE.JOB.PROD
   ...

This will have exactly the same effect as a job that actually contains all the
!FILE-equations:

   !JOB ...
   !FILE BASEAP=BASEAP.DATA
   !FILE CONFFILE=CONF1.DATA
   !FILE RPT;DEV=LP,1,1
   !FILE FTN01=LOGFILE.DATA,NEW;SAVE
   ...

Of course, the ::USE file could contain a mixture of :: commands and non-::
commands.  For instance, the FILEUSE.JOB.PROD file can actually issue one of
two different sets of !FILE commands:

   !FILE RPT;DEV=LP,outpri,1
   ::IF TESTING="Y" THEN
   !FILE BASEAP=BASEAP.TEST
   !FILE CONFFILE=CONF1.TEST
   !FILE FTN01=LOGFILE.TEST,NEW;SAVE
   ::ELSE
   !FILE BASEAP=BASEAP.DATA
   !FILE CONFFILE=CONF1.DATA
   !FILE FTN01=LOGFILE.DATA,NEW;SAVE
   ::ENDIF

Here, depending on the value of a variable TESTING (which should be ::PROMPTed
for or ::ASSIGNed to in the job stream that actually does the ::USE), either
the .TEST or the .DATA set of !FILE-equations is put into the job stream.  Also
note that the !FILE RPT equation will include the value of the variable OUTPRI,
which should also have been ::PROMPTed for or ::ASSIGNed to in the ::USEing
job.


::RETURN, STREAMX stream-time command ``use
::RETURN, STREAMX stream-time command
Aborting ::USE file execution
Stopping ::USE file execution
, in the middle of a ::USE file, you decide that you want to abort the
submission of the entire job stream, you can use the ::EXIT command (just like
you can inside the stream file itself).  If you simply want to stop processing
this ::USE file but want to continue processing the main job stream, you can
use the

   ::RETURN

command.


Including binary data in STREAMX jobs ``ascii`contents
Including binary data in STREAMX jobs

Occasionally you may want to include binary data inside job streams, usually as
input lines to some program.  This can cause a number of problems for STREAMX,
depending on what characters the binary data contains:

   * as you already know, braces ("") and question marks ("?") are
     interpreted by STREAMX as special delimiters; if they occur within your
     binary data, STREAMX will print various error messages and/or invalid
     prompt messages (this isn't really a bug -- STREAMX is doing what it's
     supposed to do -- but it isn't desirable behavior, either);

   * also, if your data happens to include two colons ("::") at the beginning
     of a line STREAMX will expect some kind of valid submission-time command,
     and will print an error if it doesn't find one;

   * a more subtle problem occurs when your data happens to include a carriage
     return character; because of the way STREAMX processes strings, everything
     on the line after the CR will be discarded.


::SETBINARY, STREAMX stream-time command ``ascii
::SETBINARY, STREAMX stream-time command
::SETASCII, STREAMX stream-time command
do you get around this problem? STREAMX has two special submission-time
commands: ::SETBINARY and ::SETASCII.

When STREAMX is processing a job stream and sees a ::SETBINARY command, it
copies all lines after that directly into the job without modifying them in any
way until it sees a ::SETASCII command.

For example, you might have a job that looks (in part) like this:

   !RUN WEIRDPRG
   ::SETBINARY
   (lines of binary data that may include ::, , , ? and CR go here)
   ::SETASCII
   !EOJ

the lines after the ::SETBINARY command are input for the program "WEIRDPRG",
and will be copied to the job stream exactly as they appear in the job file.

SETTING JOB STREAM SCHEDULING PARAMETERS


Setting job stream scheduling parameters ``contents
Setting job stream scheduling parameters


::SETSCHEDULE, STREAMX stream-time command ``schedule
::SETSCHEDULE, STREAMX stream-time command
, if you don't specify scheduling parameters when streaming a file, the
file will be submitted immediately (just like with the MPE :STREAM command).
But what if a particular file should ALWAYS be submitted with scheduling
parameters, and you don't want to risk the user's forgetting? Or what if you'd
like to prompt the user for the scheduling parameters? Or calculate them, say,
based on today's date and/or the value of the inputs that the user specifies?

With the ::SETSCHEDULE command, the job stream can specify its own scheduling
parameters, e.g.

   !JOB DELSPOOL,MANAGER.SYS; OUTCLASS=,1
   ::SETSCHEDULE AT=02:00
   ...

or

   ::SETSCHEDULE AT=?When would you like to schedule this job for?

What follows the ::SETSCHEDULE must be the :STREAM command scheduling
parameters, exactly as they'd be specified after the ";" in the :STREAM command
(e.g.  "::SETSCHEDULE AT=02:00;DAY=MONDAY").

Note that if the user explicitly specifies scheduling parameters when he runs
STREAMX (e.g.  in the STREAMX UDC), those parameters will be used and any
::SETSCHEDULE command in the file will be ignored.  This lets a user override
the ::SETSCHEDULE settings in the file.

Also note that if you specify several ::SETSCHEDULE commands in one job stream,
the FIRST one will take precedence.

ERROR HANDLING WITH THE ::TRAPERROR COMMAND


Error handling with the ::TRAPERROR command ``contents
Error handling with the ::TRAPERROR command


::TRAPERROR, STREAMX stream-time command ``error
::TRAPERROR, STREAMX stream-time command
::IFERROR, STREAMX stream-time command
::ENDIFERROR, STREAMX stream-time command
::IFCLEANUP, STREAMX stream-time command
::ENDIFCLEANUP, STREAMX stream-time command
of the most important functions of STREAMX is to allow you to detect
conditions that would prevent your jobs from completing at submission time,
rather than finding out the next day that the job didn't run because of
something that could have been fixed before streaming it.  Certain STREAMX
stream-time commands (like ::IF/::ELSE/::ELSEIF/::ENDIF) help you detect errors
(like a file that is too close to full) when you STREAM the job, and take
appropriate action at that time.  An even more elegant mechanism is provided by
the ::TRAPERROR constructs (::TRAPERROR with ::IFERROR/::ENDIFERROR or
::IFCLEANUP/::ENDIFCLEANUP).

A simple example will demonstrate the power of these commands.  First, a
typical STREAMX job without ::TRAPERROR.

   ::COMMENT The following two files MUST be built before the job
   ::COMMENT is streamed.
   ::SETJCW CIERROR = 0
   ::CONTINUE
   ::BUILD F1;DISC=1000,1,1;REC=-80,,F,ASCII
   ::IF CIERROR<>0 THEN
   ::   ECHO File could not be built.  Fix the problem and re-STREAM.
   ::   EXIT
   ::ENDIF
   ::SETJCW CIERROR = 0
   ::CONTINUE
   ::BUILD F2;DISC=1000,1,1;REC=-132,,F,ASCII
   ::IF CIERROR<>0 THEN
   ::   ECHO File could not be built.  Fix the problem and re-STREAM.
   ::   EXIT
   ::ENDIF
   ...
   !JOB NIGHTLY,MANAGER.PR
   ...
   !EOJ

Now, the same job with ::TRAPERROR.

   ::TRAPERROR
   ::BUILD F1;DISC=1000,1,1;REC=-80,,F,ASCII
   ::BUILD F2;DISC=1000,1,1;REC=-132,,F,ASCII
   ::IFERROR
   ::   ECHO File could not be built.  Fix the problem and re-STREAM.
   ::   EXIT
   ::ENDIFERROR
   ...
   !JOB NIGHTLY,MANAGER.PR
   ...
   !EOJ

Another form of the ::TRAPERROR construct allows you do several commands and
then, whether or not any of the commands failed, execute some "cleanup"
commands when they are done.

::COMMENT Build files TEMP1 and TEMP2, then run PROG1.
::COMMENT If PROG1 doesn't abort, run PROG2.
::COMMENT No matter what, purge TEMP1 & TEMP2 when done.
::BUILD TEMP1
::BUILD TEMP2
::TRAPERROR
::RUN PROG1
::RUN PROG2
::CLEANUP
::   PURGE TEMP1
::   PURGE TEMP2
::ENDCLEANUP

Finally, if you want to immediately "jump" to the IFERROR or CLEANUP block you
can use the

::ESCAPE errnum

command.  This sets HPCIERR to errnum, sets CIERROR to the absolute value of
errnum, and skips all statements until the next IFERROR or CLEANUP.  For
example:

...
::TRAPERROR
::IF VEFINFO("FILE1").EOF//VEFINFO("FILE1").FLIMIT > .80 THEN
::   ESCAPE 1
::ELSEIF VEFINFO("FILE2").EOF//VEFINFO("FILE2").FLIMIT > .80 THEN
::   ESCAPE 2
::ELSEIF VEFINFO("FILE3").EOF//VEFINFO("FILE3").FLIMIT > .80 THEN
::   ESCAPE 3
::ENDIF
...
::IFERROR
::   ECHO ERROR:
::   ECHO   FILE!HPCIERR is more than %80 full!!!
::   ECHO   Terminating job submission.
::   EXIT
::ENDIFERROR

ABORTING JOB SUBMISSION IF AN ERROR OCCURS


Aborting job stream submission if an error occurs ``contents
Aborting job stream submission if an error occurs
STREAMXPERMABORTIFERROR, STREAMX JCW to abort submission on error

Normally, if STREAMX encounters an error in a :: command, it prints an error
message and continues processing the rest of the job.  This isn't always what
you want, since many errors would keep the job from being properly assembled.

To change this, you can set the JCW STREAMXPERMABORTIFERROR to 1, which will
make STREAMX abort the job submission on the first error that occurs (though,
of course, you can prevent this by putting a ::CONTINUE before the command or
using ::TRAPERROR to trap all errors in a block of commands).

This is actually the way we recommend that you do things; however, for
compatibility reasons, we can't make it the default, since some of our users'
jobs may rely on STREAMX's not aborting in case of error in job processing.
If, however, you don't have any such jobs (or have put ::CONTINUEs in the
proper places in them), we encourage you to set a system-wide OPTION LOGON UDC
that does a :SETJCW STREAMXPERMABORTIFERROR = 1.

MORE DETAILS ON THE "XXX" SYNTAX


More details on the "XXX" syntax ``contents
More details on the "XXX" syntax


Variable substitution
Expression evaluation
Braces ("" and ""), used in STREAMX expressions
, STREAMX delimiter
the above examples, we frequently used the "xxx" syntax, by which the
expression "xxx" is evaluated and its result is inserted (in place of the
"xxx") into the job stream.  For instance, saying

   !BUILD X;DISC=1234*17

is exactly the same as saying

   !BUILD X;DISC=20978

The expression 1234*17 is evaluated and its result -- "20978" -- is substituted
in place of the string "1234*17".

As we discussed, any variable that you've ::ASSIGNed to or ::PROMPTed for can
be included in the expression.  Similarly, any MPE JCW (e.g.  HPDAY, HPMONTH,
etc.) can be used, as can be any of the many PREDEFINED VARIABLES (listed in
the Appendix).  For instance, your job stream might very well read:

   !JOB COMPILE,HPUSER.HPACCOUNT; OUTCLASS=,1
   ...
   !TELL HPUSER.HPACCOUNT COMPILE DONE!
   !EOJ

HPUSER is a variable that contains the name of the user streaming the job;
HPACCOUNT is a variable that contains the name of the account streaming the
job.  Thus, this job will always log on as the same user and account as the
person streaming it; when it's done, it will send the COMPILE DONE message to
its originator.  If JOE.AP tries to stream it, the job will look like

   !JOB COMPILE,JOE.AP; OUTCLASS=,1
   ...
   !TELL JOE.AP COMPILE DONE!
   !EOJ

If MANAGER.PAYROLL streams it, the job will look like

   !JOB COMPILE,MANAGER.PAYROLL; OUTCLASS=,1
   ...
   !TELL MANAGER.PAYROLL COMPILE DONE!
   !EOJ

Another interesting trick you can do with predefined variables is to have the
final !TELL command say:

   !TELL #SHPJOBNUM COMPILE DONE!

This will send the message to the session that actually submitted the job
(which is what HPJOBNUM refers to) -- thus, if there are ten users logged on as
MANAGER.PAYROLL, only the one who actually streamed it would get the message.

A special use for the "xxx" syntax is within a ?$LOCKWORD= construct.  For
example, you can say

   ::ASSIGN QUERYLOC = "PUB.VESOFT"
   ...
   !RUN ?$LOCKWORD=QUERY.QUERYLOC$?

SUMMARY OF THE ?XXX?, ::XXX, AND XXX FEATURES


Summary of the ?XXX?, ::XXX and XXXfeatures ``contents
Summary of the ?XXX?, ::XXX and XXX features

Questions embedded into a line in the job stream:

   ?QUESTION?                               Prompts for input

   ?$CINTEGER$QUESTION?                     Prompts for an integer

   ?$CDATEYMD$QUESTION?                     Prompts for a [YY]YY/MM/DD date

   ?$CDATEMDY$QUESTION?                     Prompts for a MM/DD/[YY]YY date

   ?$CDATEDMY$QUESTION?                     Prompts for a DD/MM/[YY]YY date

   ?$NOECHO$QUESTION?                       Prompts without echo

   ?$DEFAULT="DEF"$QUESTION?                Prompts with a default


Lockwords

  ?$LOCKWORD=FILENAME$?                    Inserts the given filename with
                                       it's lockword (prompting if necessary)

   ?$option;option$question?                Two or more options may be combined
                                       by separating them with semicolons

STREAMX commands that start with "::": (These commands are executed at stream
time, and are not copied into the generated job stream.)

   ::ECHO text                              Prints "text" to the terminal.

   ::PROMPT STRING var = "promptstr"        Prompts for a string variable
                                       called "var".

   ::PROMPT INTEGER var = "promptstr"       Prompts for an integer variable
                                       called "var".

   ::PROMPT DATE var = "promptstr"          Prompts for a date variable called
                                       "var"; input format must be [YY]YY/MM/DD
                                       (with or without slashes).

   ::PROMPT DATE var = "promptstr"; CDATEYMD
                                       Prompts for a [YY]YY/MM/DD date.

   ::PROMPT DATE var = "promptstr"; CDATEMDY
                                       Prompts for a MM/DD/[YY]YY date.

   ::PROMPT DATE var = "promptstr"; CDATEDMY
                                       Prompts for a DD/MM/[YY]YY date.

   ::PROMPT type var = "promptstr"; CHECK=(expression)
     (type=DATE/INTEGER/STRING)        Prompts for a variable, checking to make
                                       sure that the CHECK= expression is true.
                                       If it isn't, prompts the user again
                                       until the expression becomes true.

   ::PROMPT type var = "promptstr"; CHECK=(exp); CHECKERROR="errormsg"
                                       Prompts for a variable until the CHECK=
                                       expression becomes TRUE; while it's
                                       FALSE, prints the error message and
                                       prompts again.

   ::PROMPT type var = "promptstr"; NOECHO
                                       Prompts for a variable without echo.

   ::PROMPT type var = "promptstr"; DEFAULT="default"
                                       Prompts for a variable with a default
                                       value (a value to be used if the user
                                       hits return).

   Any of the above keywords can be combined by separating them with
   semicolons, e.g.  ::PROMPT DATE R = "Date"; CDATEYMD; NOECHO.

   ::ASSIGN var = expression           Evaluates an expression and assigns it
                                       to a variable.

   ::IF expression THEN                     Checks the expression and
     ...                                    executes one or another part
   ::ELSE                                   of the ::IF/::ELSE/::ENDIF
     ...                                    construct.
   ::ENDIF

   ::WHILE expression                       Executes the commands between
     ...                                    the ::WHILE and the ::ENDWHILE
   ::ENDWHILE                               as long as the ::WHILE
                                            expression is true.

   ::SETQUESTION x                     Sets the "?" delimiter character to some
                                       other value (see below).

   ::SETBRACES xy                      Sets the "" delimiter character to "x"
                                       and the "" delimiter character to "y"
                                       (see below).

   ::SETSCHEDULE scheduleparms         Sets the scheduling parameters (AT=,
                                       IN=, etc.) for this job stream.

   ::command                           Executes the given MPE command at stream
                                       time.

The "xxx" construct evaluates the expression "xxx" and inserts it into the
job stream.  There are many such useful, valuable expressions; some good
examples are:

   !BUILD FILENAME;CODE=123          Substitutes the value of the FILENAME
                                       variable into the job.

   !RUN MYPROG;INFO="TODAY-10"       Calculates the date expression "today
                                       minus 10 days" and substitutes it in
                                       YY/MM/DD form.

   CDATE(RDATE,'MM/DD/YY')           Substitutes the value of the date
                                       variable RDATE in MM/DD/YY format.

   !TELL HPUSER.HPACCOUNT DONE!    Substitutes the predefined variables
                                       HPUSER (user name of the streaming user)
                                       and HPACCOUNT (account name of the
                                       streaming user) into the !TELL command.

   !BUILD X;DISC=VEFINFO(F).FLIMIT+100 Calculates the file limit of the file
                                       whose name is stored in the variable F,
                                       adds 100 to it, and puts the result into
                                       the !BUILD command.


STREAMX and !REMOTE HELLO ``contents
STREAMX and !REMOTE HELLO

Just as you shouldn't have embedded passwords in !JOB cards, so you shouldn't
have embedded passwords in !REMOTE HELLOs.  STREAMX can let you avoid embedded
!REMOTE HELLO passwords.

Whenever STREAMX sees a !JOB card, it can automatically find out (from the
system directory) the correct passwords, check to make sure that you're
authorized to submit the job (perhaps by prompting you for the passwords), and
then do the :STREAM.

Unfortunately, !REMOTE HELLOs can't be handled exactly the same way -- STREAMX
can't automatically find out the correct remote passwords, since they're not
kept on the computer on which STREAMX is running.

We might have made STREAMX do a :REMOTE HELLO of its own in order to get the
remote passwords using a special "helper" program running on the remote
computer, but that would have had its own problems.  It would have taken more
time (:REMOTE HELLOs are rather slow) and might have compromised the security
of the remote machine -- if you have a very tightly secured production machine
linked to a not so tightly secured development machine, you wouldn't want a
user (even an SM user) on the development machine to be able to get arbitrary
passwords from the production machine.

Therefore, since STREAMX can't get remote password information itself, the
system manager will have to provide some of this information to STREAMX (by
means of a special configuration file about which we'll say more shortly).

   * He may tell STREAMX which remote users, accounts or groups have passwords
     (so STREAMX will know when to prompt a user who is submitting the job
     stream).

   * He may tell STREAMX that the remote passwords are the same as the local
     passwords (which is frequently the case with small networks in which all
     the CPUs are controlled by the same people).

   * Or, he may tell STREAMX what exactly the remote passwords (or some of the
     remote passwords) are.  In this case, he can also indicate (using the
     STREAMX.DATA.VESOFT file) which users can submit job streams that do
     !REMOTE HELLOs without being prompted for the passwords; all other users
     (except SM) will be prompted.

In the last two cases (equal passwords and explicitly specified passwords),
STREAMX will behave much like it does for normal !JOB card passwords -- it will
either put in the passwords itself (if the user's capability warrants this or
if the user was specifically allowed this by the STREAMX.DATA.VESOFT file) or
prompt the user for the passwords and check to make sure that the user inputs
the right values.

Even if you do specify the remote passwords in the configuration file, you're
still much better off than you'd be if the passwords were embedded in each job
stream.

   * First of all, the configuration file can be much better secured than all
     your job streams (in fact, you can secure it so that only the system
     manager can access it).

   * Secondly, you can use $NOPASS to allow particular users to submit
     particular jobs that !REMOTE HELLO using certain passwords without having
     those users know the passwords.

   * Finally, if you change the remote passwords, you only need to change one
     configuration file -- no need to find and change all the job streams that
     do !REMOTE HELLOs.

So how exactly does this configuration file business work? Well, say that a job
stream on system ALPHA tries to do a !REMOTE HELLO onto system BETA:

     !JOB AP010,PROD.AP; OUTCLASS=,1
     ...
     !DSLINE BETA
     !REMOTE HELLO REMUPDAT,BATCH.GL
     ...


PASSFILE.VESOFT group, remote system passwords
order for STREAMX to be able to handle this, there has to be a file on
system ALPHA (the system of the !JOB) called BETA.PASSFILE.VESOFT -- the name
of the file must match the nodename of the remote node, not the $SYS-NAME in
the SECURCON.DATA.VESOFT file or the envid from the !DSLINE envid=nodename or
!REMOTE:envid=nodename commands (to use a different filename, see "Changing The
Password Filename" below).  (If there is no such file, STREAMX won't touch the
!REMOTE HELLO; the !REMOTE HELLO will then have to have the correct passwords
embedded in it, just as it would without STREAMX.) This BETA.PASSFILE.VESOFT
file contains (for the benefit of STREAMX running on system ALPHA) information
on passwords of system BETA.


ACCOUNT, sysname.PASSFILE.VESOFT keyword ``ns
$ACCOUNT, sysname.PASSFILE.VESOFT keyword
$USER, sysname.PASSFILE.VESOFT keyword
$GROUP, sysname.PASSFILE.VESOFT keyword
$EQUAL, sysname.PASSFILE.VESOFT keyword
simple BETA.PASSFILE.VESOFT file might say:

     $ACCOUNT @ $EQUAL
     $USER @.@ $EQUAL
     $GROUP @.@ $EQUAL

This means:

   * The passwords for all ("@") the accounts on system BETA are the same
     ("$EQUAL") as the account passwords on system ALPHA.

   * The passwords for all ("@.@") the users on system BETA are the same as the
     user passwords on system ALPHA.

   * The passwords for all the groups on system BETA are the same as the group
     passwords on system ALPHA.

Given this information, STREAMX now knows all about the system BETA passwords.
It can prompt the user for the correct BATCH.GL passwords or, if the user
streaming the job stream is already logged on as BATCH.GL, account manager of
the GL account or a user with SM, put the passwords in automatically without
prompting.

What if only your DEV account passwords are actually the same on ALPHA and
BETA, and all the other passwords are different? Your BETA.PASSFILE.VESOFT file
might then say:

     $ACCOUNT DEV $EQUAL
     $USER @.DEV $EQUAL
     $GROUP @.DEV $EQUAL
     $ACCOUNT GL TOPSEC
     $USER BATCH.GL GAMALIEL

The first three lines are just like the $EQUAL lines in the previous example
except that they only apply to DEV account passwords.  The fourth line says
"$ACCOUNT GL TOPSEC", which simply means that the GL account password is
TOPSEC; the fifth line says "$USER BATCH.GL GAMALIEL", which means that the
BATCH.GL user password is GAMALIEL.

Now, when a user streams our sample job stream (which does a "!REMOTE HELLO
BATCH.GL"), STREAMX will know that the passwords are TOPSEC and GAMALIEL.  If
the user has SM capability or is specifically permitted by the
STREAMX.DATA.VESOFT file (more about this soon), STREAMX will automatically
substitute the correct passwords into the !REMOTE HELLO; otherwise, STREAMX
will prompt the user for the passwords and refuse to stream the job stream
until the user actually enters the right ones.

Note that if the user is logged on as BATCH.GL or as a GL account manager on
system ALPHA, he will still be prompted for the passwords, even though the
remote logon is also BATCH.GL.  The passwords on system ALPHA and system BETA
are, after all, quite likely to be different -- just because a user could log
on to system ALPHA as BATCH.GL doesn't mean that he should also be allowed to
log on to system BETA as BATCH.GL.

The system manager of system ALPHA, however, won't be prompted for the BATCH.GL
passwords in this example -- after all, if the passwords are explicitly
specified in BETA.PASSFILE.VESOFT, the system manager can get to them anyway.

What if the passwords on system ALPHA and system BETA are different but you
don't want to keep system BETA's passwords anywhere on system ALPHA? Perhaps
you don't even want system ALPHA's system manager to know them!

In this case, instead of putting, say, "$USER BATCH.GL $EQUAL" or "$USER
BATCH.GL GAMALIEL" in the BETA.PASSFILE.VESOFT file, you can instead say:


EXIST, sysname.PASSFILE.VESOFT keyword ``ns
$EXIST, sysname.PASSFILE.VESOFT keyword
$PROMPT, sysname.PASSFILE.VESOFT keyword

     $ACCOUNT DEV $EQUAL
     $USER @.DEV $EQUAL
     $GROUP @.DEV $EQUAL
     $ACCOUNT GL $EXIST
     $USER BATCH.GL $PROMPT

The GL account's password was specified as "$EXIST", which merely tells STREAMX
that the remote GL account does indeed have a password.  If STREAMX didn't know
this then it wouldn't prompt for the GL account password; it would simply keep
the !REMOTE HELLO the same as it was before -- with the password if one was
specified or without it if it wasn't.  But, because STREAMX knows that the GL
account has a password, it will prompt the streaming user for it.

Of course, since STREAMX doesn't actually know what the remote GL password is,
it won't be able to check whether the password that the user input is correct.
If the user inputs the wrong password, the job will still be submitted, but the
!REMOTE HELLO will naturally fail because the wrong password was specified.

The BATCH.GL user's password was not specified as "$EXIST" but rather as
"$PROMPT".  $PROMPT is just like $EXIST in that it tells STREAMX that a remote
password does indeed exist; however, it requires STREAMX to prompt the user for
the password even if the password is already embedded in the !REMOTE HELLO
command.  Thus, if the job stream said

     !REMOTE HELLO BATCH.GL

then (according to the BETA.PASSFILE.VESOFT keywords we indicated above)
STREAMX would prompt the user for both the BATCH.GL and GL passwords; however,
if the job stream said

     !REMOTE HELLO BATCH/XYZZY.GL/PLUGH

then STREAMX would prompt the user for the BATCH.GL password even though one
was specified in the !REMOTE HELLO.  The GL account password will not be
prompted for because it was specified as "$EXIST" and was embedded in the
!REMOTE HELLO; however, since the BATCH.GL password was specified as "$PROMPT",
it will always be prompted for.  $PROMPT is thus a good way of discouraging
people from embedding particular passwords in !REMOTE HELLOs, since the
embedded passwords will be ignored.

Let's look closely at another example:

     THE JOB STREAM "MYJOB":
         ...
         !DSLINE BETA
         !REMOTE HELLO RYAN.PROD
         ...

     THE "BETA.PASSFILE.VESOFT" FILE:
         $ACCOUNT PROD MYPASS
         $USER RYAN.PROD $EXIST

     THE CONVERSATION AT THE TERMINAL:
         :STREAM MYJOB       << a UDC that runs STREAMX >>
         STREAMX/3000 Version 27Nymmdd
         ...
         COMMAND = !REMOTE HELLO RYAN.PROD
         ENTER PROD ACCOUNT PASSWORD:    << user types FOO, echo off >>
         INCORRECT PASSWORD.  (CIERR 1441)
         ENTER PROD ACCOUNT PASSWORD:    << user types MYPASS >>
         ENTER RYAN USER PASSWORD:    << user types ABRACADA >>
         ...

     THE JOB STREAM GENERATED BY STREAMX:
         ...
         !DSLINE BETA
         !REMOTE HELLO RYAN/ABRACADA.PROD/MYPASS

STREAMX knew (because the BETA.PASSFILE.VESOFT told it) that PROD's account
password was MYPASS and that RYAN.PROD had a password, though STREAMX didn't
know exactly what that was.  When the user entered the wrong PROD account
password, STREAMX printed an error message and re-prompted him; when the user
entered a RYAN user password, STREAMX just accepted it without knowing whether
or not it was correct.

If the streaming user had SM capability or was specifically allowed to stream
this file without supplying passwords (using the STREAMX.DATA.VESOFT file,
which we'll talk about shortly), he would not have been prompted for the PROD
password -- STREAMX would have automatically put it in.  He would still have
been prompted for the RYAN.PROD password, since STREAMX wouldn't have known
what the correct password was.

If the RYAN.PROD password was embedded in the original !REMOTE HELLO -- i.e.
if the stream file said

     !REMOTE HELLO RYAN/ABRACADA.PROD

then the streaming user would not have been prompted for the RYAN.PROD
password.  However, the PROD account password would have still been prompted
for or automatically substituted, whichever was appropriate.

To summarize:

   * If a job from system ALPHA tries to !REMOTE HELLO to system BETA, STREAMX
     will look in the file BETA.PASSFILE.VESOFT on system ALPHA.

   * If the file BETA.PASSFILE.VESOFT does not exist OR the user, account or
     group given in the !REMOTE HELLO is not mentioned in BETA.PASSFILE.VESOFT,
     the job stream that STREAMX generates will have exactly the same password
     in the !REMOTE HELLO as was embedded in the original file's !REMOTE HELLO
     or no password if no password was embedded in the original file.

     In other words, if you don't do anything, the !REMOTE HELLOs will work
     exactly the same way as they would without STREAMX.

   * The file BETA.PASSFILE.VESOFT should contain a series of triplets.  Each
     triplet should include:

       - The word $USER, $ACCOUNT or a $GROUP, specifying the kind of password
         that this triplet is describing.

       - The userset (e.g.  "@.DEV"), accountset (e.g.  "DEV@") or groupset
         (e.g.  "PUB.GL@") whose password is being described.  As you can see,
         wildcards (@, ?, and #) are permitted.

       - Either:

           * The exact password of the user, account or group.

           * $EQUAL, indicating that the passwords on the remote machine are
             the same as on the local.

           * $EXIST, indicating that the passwords on the remote machine exist
             and should be prompted for if they're not already embedded in the
             !REMOTE HELLO.

           * $PROMPT, indicating that the passwords on the remote machine exist
             and should be prompted for even if a password is embedded in the
             !REMOTE HELLO.

           * $DEFAULT, indicating that the password embedded in the !REMOTE
             HELLO should be used; if no password is embedded in the !REMOTE
             HELLO, no password should be used in the STREAMX-generated job
             stream.  This is the same as having no entry for this password at
             all, but may be necessary if otherwise the user, account or group
             in question would match one of the other $USER/$ACCOUNT/$GROUP
             commands.

     Line boundaries don't really matter, though we recommend that each triplet
     start on a new line.  You can easily split the components of a triplet
     across several lines, but only between the three elements, not in the
     middle of an element.  In other words,

          $USER
            @.PROD-MGR.PROD-RYAN.PROD
              $EQUAL

     is all right, but

          $USER @.PROD-MGR.PROD-
                RYAN.PROD $EQUAL

     is not.  If you need to split a userset (or accountset or groupset) over
     several lines, you must put a "&" character at the end of each line to be
     continued (just as in the STREAMX.DATA.VESOFT and SECURCON.DATA.VESOFT
     files), e.g.

          $USER @.PROD-MGR.PROD-&
                RYAN.PROD $EQUAL

   * If a particular user, account or group matches more than one of the
     usersets, accountsets or groupsets specified in the PASSFILE.VESOFT file,
     the LAST ONE MATCHED will take effect.  Thus, you should put the most
     general ones first and the more specific ones later.  For example,

          $USER @.@ $EQUAL
          $ACCOUNT @ $EQUAL
          $GROUP @.@ $EQUAL
          $USER @.SYS $PROMPT
          $USER ACCESS.SYS BANANA

     indicates that all the passwords are the same on both systems, except that
     all SYS account passwords should be prompted for, but the ACCESS.SYS
     password is BANANA.

$NOPASS AND !REMOTE HELLO


NOPASS and !REMOTE HELLO ``contents
$NOPASS and !REMOTE HELLO


HOST=, keyword in STREAMX.DATA ``remote
HOST=, keyword in STREAMX.DATA
you know, the STREAMX.DATA.VESOFT lets you specify that particular users are
allowed to stream particular job stream files that log on in a particular way
without being prompted for passwords.

Thus, if your STREAMX.DATA.VESOFT file says:

     $NOPASS OPERATOR.SYS @.BATCH.SYS BACKUP.SYS

this means that if the user OPERATOR.SYS streams any file in the group
BATCH.SYS that logs on as the user BACKUP.SYS, he will not be prompted for
passwords.  STREAMX will automatically put in the correct passwords even though
they were neither embedded in the job stream nor specified by the user because
the system manager -- by putting the $NOPASS record into the
STREAMX.DATA.VESOFT file -- explicitly authorized this.

This feature is equally valuable for remote logons.  For instance, let's say
that your BETA.PASSFILE.VESOFT file says

     $USER MILLARD.PAYROLL MOREFILL

(indicate that MILLARD.PAYROLL's password on system BETA is MOREFILL).  And,
let's say that you want to let the user MGR.PAYROLL stream jobs that do !REMOTE
HELLOs as MILLARD.PAYROLL, e.g.

     !JOB ...
     ...
     !DSLINE BETA
     !REMOTE HELLO MILLARD.PAYROLL
     ...


DSLINE=, $NOPASS parameter in STREAMX.DATA
, all you have to do is add a line to your STREAMX.DATA.VESOFT file (on
system ALPHA, the local system) that says

     $NOPASS MGR.PAYROLL @.@.@ MILLARD.PAYROLL;DSLINE=BETA

This says: "if MGR.PAYROLL streams any file (@.@.@) that logs on as
MILLARD.PAYROLL onto system BETA, then automatically substitute in the correct
MILLARD.PAYROLL password from the BETA.PASSFILE.VESOFT file".

Similarly, say that there are certain system maintenance job streams that
OPERATOR.SYS streams that should be able to !REMOTE HELLO to any user in the
SYS account on system BETA.  All these jobs are kept in the group BATCH.SYS (to
which OPERATOR.SYS probably shouldn't even have write or save access).  By
saying

     $NOPASS OPERATOR.SYS @.BATCH.SYS @.SYS;DSLINE=BETA

you will let OPERATOR.SYS stream these jobs without having to enter the remote
passwords.  Note that you must still put the correct passwords into the
BETA.PASSFILE.VESOFT file; it is the PASSFILE.VESOFT file that tells STREAMX
what the passwords really are -- STREAMX.DATA.VESOFT only tells STREAMX who can
have them automatically substituted in their jobs without being prompted.

Actually, in the example we just gave, you might very well want to have your
STREAMX.DATA.VESOFT file say

     $NOPASS OPERATOR.SYS @.BATCH.SYS @.SYS
     $NOPASS OPERATOR.SYS @.BATCH.SYS @.SYS;DSLINE=BETA

thus preventing OPERATOR.SYS from being prompted for either the local or the
remote SYS user/group/account passwords (as long as he's streaming files in
BATCH.SYS).

Note, however, that the two $NOPASSes are entirely separate, and, as far as
STREAMX is concerned, unrelated.  If only the first line was specified,
OPERATOR.SYS would be prompted for remote SYS user/group/account passwords; if
only the second line was specified, OPERATOR.SYS would be prompted for local
SYS user/group/account passwords.

Each $NOPASS line that doesn't specify a ;DSLINE= only applies to the local
system; each $NOPASS line that does specify a ;DSLINE= applies only to the
remote system indicated, not to the local system or any other system.

What happens if more than one $NOPASS with a ;DSLINE= applies to the same job?
Just like LOGON does with SECURCON.DATA.VESOFT file, STREAMX will use the last
$NOPASS that applies to the job and the streaming user.

As in the SECURCON.DATA.VESOFT file, this can be quite useful.  For instance,

     $NOPASS  OPERATOR.SYS  @.JOB.SYS  OPERATOR.SYS;DSLINE=@
     $NOPASS  OPERATOR.SYS  @.JOB.SYS  USER.TEST;DSLINE=BETA

means:

   1) OPERATOR.SYS can stream any file in the group JOB.SYS and that logs on to
      any other system as OPERATOR.SYS (without being prompted for remote
      passwords) unless
   2) the job logs on to system BETA, in which case he will be
      prompted for remote passwords for OPERATOR.SYS but not for USER.TEST.

CHANGING THE PASSWORD FILENAME


Changing the password filename ``contents
Changing the password filename

So far, we've always called the file that contains the remote password
information -- the "passfile" -- BETA.PASSFILE.VESOFT.  This is because our
examples said

     !DSLINE BETA
     !REMOTE HELLO ...

and STREAMX, seeing that we were using DSLINE BETA, assumed that the passfile's
name was BETA.PASSFILE.VESOFT.

What if instead of "!DSLINE BETA" we said "!DSLINE 90"? Well, since MPE
filenames must start with a letter, not a digit, STREAMX would have put an "N"
(for Number) in front of the filename, thus looking for the passfile as
N90.PASSFILE.VESOFT.

But what if we said "!DSLINE BETA.GAMMA.DELTA"? Or what if we sometimes said
"!DSLINE BETA" and sometimes said "!DSLINE 90", but didn't want to keep two
different passfiles for the same remote machine?

Well, we let you put records into the STREAMX.DATA.VESOFT file that say


PASSFILE, STREAMX configuration keyword ``remote
$PASSFILE, STREAMX configuration keyword

   $PASSFILE nodename filename

e.g.

   $PASSFILE X.Y.Z ZFILE
   $PASSFILE 90 BETA

In the above example, whenever STREAMX saw a !REMOTE HELLO using the DSLINE (or
NS/3000 node name) "X.Y.Z", it would look in the file ZFILE.PASSFILE.VESOFT for
password information; whenever it saw a !REMOTE HELLO using DSLINE 90, it would
look in the file BETA.PASSFILE.VESOFT.

The default (same name as DSLINE, except that numeric DSLINEs are prefixed with
"N") still applies; however, $PASSFILE lets you override this default whenever
you want to.

Since both the $PASSFILE records and the $NOPASS records have to be specified
in the STREAMX.DATA.VESOFT, they can be intermingled in any way you like.
There's no specific order in which they must be.

HOW STREAMX RECOGNIZES DSLINEs


How STREAMX recognizes DSLINEs ``contents
How STREAMX recognizes DSLINEs

In order to find the right passfile and the applicable $NOPASS records, STREAMX
has to be able to tell which DSLINE (or network node) is being used in a
particular !REMOTE HELLO.  There are several ways in which STREAMX figures this
out:

   * If you say

          !REMOTE HELLO U.A;DSLINE=ABC

     then STREAMX will look at the ;DSLINE= value.

   * If you say

          !REMOTE:ABC HELLO U.A

     then STREAMX will look at the data between the first ":" and the first
     space immediately following the ":" (in this case, "ABC").

   * If you say

          !REMOTE HELLO U.A

     without specifying a ":ABC" or a ";DSLINE=ABC", STREAMX will look for the
     IMMEDIATELY PRECEDING "!DSLINE" command.  Thus, if you say

          !DSLINE ABC
          !...
          !REMOTE HELLO U.A

     STREAMX will still recognize this as a !REMOTE HELLO to ABC, provided
     there were no other !DSLINE commands in between.

   * Finally, if you use the "!DSLINE X=ABC" syntax, STREAMX will correctly
     recognize that the "name" of the computer being logged on to is actually
     ABC, not X.

PROTECTING PASSFILEs


Protecting PASSFILEs ``contents
Protecting PASSFILEs

Naturally, passfiles should be very well-secured.  When we build the
PASSFILE.VESOFT group, we build it with access restricted to MANAGER.VESOFT and
users with SM capability -- this should prevent anybody else from looking at
any of the passfiles.

If you want to, you can even put a lockword on the passfiles -- STREAMX will be
able to open the file anyway (without prompting the user for the lockword).
However, our default PASSFILE group security (R,A,W,L,X,S:GU) should be
sufficient to protect the passfiles.

!REMOTE HELLO PROCESSING IN LOGON MENUS AND IN MPEX


!REMOTE HELLO processing in logon menus and in MPEX ``contents
!REMOTE HELLO processing in logon menus and in MPEX


Logon menus and !REMOTE HELLO
as you can tell STREAMX to automatically prompt for and/or automatically
substitute !REMOTE HELLO passwords, so you can have SECURITY logon menus and
even MPEX command files do the same thing.

The mechanism for doing this is exactly the same as the one you use in STREAMX
-- you put the password information into the appropriate "passfile" and
SECURITY and MPEX will, before executing any REMOTE HELLO command, look up the
appropriate passwords and either automatically embed them into the command or
prompt the user for them.

Thus, you can avoid embedding passwords in your logon menus and in your MPEX
command files (or even UDCs).  For instance, if your logon menu (called
CLRKMENU.DATA.AP) says

   *CAPTION RUN GENERAL LEDGER
   REMOTE HELLO REMCLERK.GL;DSLINE=SYSB
   REMOTE RUN ...
   REMOTE BYE
   ...

and you have an entry in your STREAMX.DATA.VESOFT file that says

   $NOPASS @.AP CLRKMENU.DATA.AP REMCLERK.GL;DSLINE=SYSB

and your SYSB.PASSFILE.VESOFT file says

   $USER REMCLERK.GL CLRKPASS
   $ACCOUNT GL SUSIE

then SECURITY will realize that the remote passwords are CLRKPASS and SUSIE and
that the user is entitled to have them automatically substituted into the
REMOTE HELLO command (as per the $NOPASS line).  The REMOTE HELLO will then be
done without any password prompting and without any need for embedding
passwords.

Note that, instead of the stream filename, the second parameter in the $NOPASS
line is now the menu file name.  Similarly, it can be the name of an MPEX
command file or even of a UDC file which contains a UDC that is executed from
MPEX and does a REMOTE HELLO.  In general, the second parameter of a $NOPASS
refers to the file (stream file, menu file, USE file, command file or UDC file)
that contains the REMOTE HELLO command.


Saving STREAMX-processed jobs ``contents`save
Saving STREAMX-processed jobs

Sometimes you may want STREAMX to save a processed job stream -- with all the
:: commands executed, all the questions answered, possibly all the passwords
inserted -- in a file instead of submitting it directly.  There are several
possible reasons for you to want this:

   * You may want to save the file -- with all the answers to the embedded
     prompts included -- for future re-submission.  (For instance, if the job
     is to be re-streamed after a coolstart -- the resubmitter might not know
     what input values the original submitter entered.)

   * You may want to just look at the processed job stream to make sure that
     it's the way you want it to be.  STREAMX has so many features that STREAMX
     job streams can become little "programs" of their own -- seeing the
     processed job stream can be a useful debugging tool.

   * You may want to pre-process the job stream using STREAMX's powerful
     constructs (::PROMPT, ::IF, ::WHILE, xxx, etc.) but then submit it not
     via the :STREAM command but through some sort of job scheduler (e.g.
     SLEEPER).

How can you accomplish this? Well, you should simply do the following:

   * Issue a file equation for the file STRMSAVE indicating the file into which
     you want to save the job stream.  The file should not already exist (or
     else you'll get a DUPLICATE PERMANENT FILE error message).  Your file
     equation might look like:


STRMSAVE, :FILE-equation for STREAMX save files

          :FILE STRMSAVE=MYSAVJOB

   * Run STREAMX.PUB.VESOFT with ;PARM=%40 (for interactive mode) or ;PARM=%41
     (for immediate mode).  In other words, if you want to run STREAMX in
     immediate mode (i.e.  streaming the file equated to STRMFILE) and in "save
     job stream" mode, you should say


PARM=%41, STREAMX option for saving the generated job
PARM=%40, STREAMX option for saving the generated job

          :FILE STRMSAVE=MYSAVJOB
          :FILE STRMFILE=MYFILE
          :RUN STREAMX.PUB.VESOFT;PARM=%41

     Immediate mode is represented by ;PARM=1; save job stream mode is
     represented by ;PARM=%40; the combination is ;PARM=%41.

Thus, you might set up a UDC called STREAMSAVE that looks like


PARM=%141, STREAMX option for saving jobs without passwords
PARM=%100, STREAMX option for saving jobs without passwords

     STREAMSAVE FILENAME=$STDIN,COLONREPL=" ",SAVEFILE=$STDLIST
     comment   This UDC preprocesses (using STREAMX) the file
     comment   FILENAME and writes the result to the file SAVEFILE.
     comment   If an alternate colon replacement character (other
     comment   than the default !) is needed, it should be
     comment   specified as COLONREPL.
     comment   Thus, "STREAMSAVE MYFILE,,MYSAVJOB" will preprocess
     comment   MYFILE and put the results into MYSAVJOB.
     FILE STRMSAVE=!SAVEFILE
     FILE STRMFILE=!FILENAME
     RUN STREAMX.PUB.VESOFT;PARM=%141;INFO="!COLONREPL"
     RESET STRMFILE
     RESET STRMSAVE

Note that in our UDC, we've specified ;PARM=%141, not just ;PARM=%41.  Why
%141?

It's not at all a good idea to keep permanent disc files with embedded
passwords.  (We've mentioned this often earlier in the manual -- somebody might
learn the passwords from the disc file, and even if the file is secured, having
embedded passwords makes it more difficult for you to change the passwords.)

Saying ;PARM=%141 tells STREAMX not to put any passwords into the saved job
stream file.  This makes it impossible for you to directly :STREAM it with MPE,
but it still permits you to submit the file with STREAMX.  And, it avoids the
security breach of embedded passwords.  (Of course, if you really need the
passwords to be saved, you can run STREAMX with ;PARM=%41 instead of
;PARM=%141.)


PARM=%341, STREAMX option for saving jobs without lockwords
PARM=%200, STREAMX option for saving jobs without lockwords
, it would be even better to say ;PARM=%341 (not just ;PARM=%141) -- by
adding %200 to the ;PARM= value, we tell STREAMX not to embed any lockwords
generated by ?$LOCKWORD=xxx$? constructs in the saved job stream.  If, for
instance, you say:

   !RUN ?$LOCKWORD=MYPROG.PUB.PROD$?

in your job stream, then a ;PARM=%41 or a ;PARM=%141 will generate a

   !RUN MYPROG/LOCK.PUB.PROD

(if "LOCK" is actually the lockword of MYPROG).  If you use ;PARM=%341, then
the saved stream file will instead contain

   !RUN ?$LOCKWORD=MYPROG.PUB.PROD$?

-- just as the original did.  This way, the saved file will still be streamable
using a future execution of STREAMX but will not actually contain the lockword.

Note that we intentionally didn't put in an option to just write the filename
without the lockword (in this case, !RUN MYPROG.PUB.PROD).  If we had this
option, then the saved file it would generate would be completely unstreamable
-- either with :STREAM or with STREAMX -- because it would always get a
lockword violation on MYPROG.

For security reasons, when you use the "save processed job stream" option,
STREAMX imposes a few additional security constraints on you:

   * It only lets you submit files that you have read access to.  If you have
     Execute access to a file but not Read access, you can normally submit it
     with STREAMX; however, you can't submit it if you use the "save job"
     option.

     The reason for this is pretty clear -- the very point of allowing Execute
     but not Read access to a job stream is to let people stream it without
     letting them read it; when one uses the "save job" option, one will
     obviously be able to see the contents of the file.

   * It ignores the $NOPASS keywords in the STREAMX.DATA.VESOFT file.  $NOPASS
     lets you stream a job stream without knowing its passwords -- naturally,
     if we wrote these passwords (that you're not supposed to know) into the
     STRMSAVE file, you'd be able to look at the file and figure them out.

     Thus, if you're using the ;PARM=%41 option and we run into a password that
     you'd normally not have to supply (because of a $NOPASS keyword in
     STREAMX.DATA.VESOFT), we will prompt you for the password and expect you
     to provide it.

     Of course, this does not apply when you're using the ;PARM=%141 option and
     don't want to save the passwords in any event.

Finally, a couple of other important points:

   * If any of the jobs in your stream file log on to a user that is protected
     by SECURITY passwords in batch (using the $BATCH-VEPROFILE keyword), then
     the saved job will not be directly :STREAMable.  This is because STREAMX
     would have to be involved in the actual :STREAMing of the job stream in
     order to notify SECURITY that it's OK to submit the jobs.

     However, the "save job" feature can still be useful in this case for
     debugging purposes.

   * If a job in your stream file streams another file, the output in the save
     file will look somewhat unusual.  First of all, the outer job stream and
     the inner job stream will be merged into one; instead of the STREAM
     command, you'll see a "!RUN STREAMX.PUB.VESOFT..."; and, the merged-in
     contents of the inner job stream will be indented by one space.  For
     instance, if the input job stream was

          !JOB OUTER,USER.ACCT
          ...
          !STREAM JINNER
          ...

     the output would be

          !JOB OUTER,USER.ACCT
          ...
          !COMMENT   :STREAM JINNER.GROUP.ACCT
          !RUN STREAMX.PUB.VESOFT;PARM=5;INFO='!?'
           !JOB MANAGER.SYS,PUB;&     << from inner job stream >>
           !OUTCLASS=,1
           !...
          ...

     You could actually stream the saved job file with the :STREAM command and
     it would work just fine (after all, that's what STREAMX does normally).
     However, if you use STREAMX to resubmit the saved job, STREAMX will not
     recognize the inner job properly (since there's no !STREAM command for it
     and the second !JOB card is indented by a space), and will thus not do any
     special processing -- e.g.  further password substitution or SECURITY
     authorization (if you use $BATCH-VEPROFILE).

     In short, if your job stream streams another job stream file, the
     resulting job stream will:

        - look somewhat unusual,

        - still be :STREAMable (if, say, you want to feed it to a job
          scheduler), and

        - be STREAMXable unless any of the inner jobs need further password
          substitution or log on as SECURITY $BATCH-VEPROFILE protected users.


Other STREAMX features ``contents
Other STREAMX features

-- ENHANCED $STDLISTs


Enhanced $STDLISTs ``contents
Enhanced $STDLISTs

One of the other major advantages of STREAMX is its Enhanced Job $STDLIST
feature.  Say that the user JOAN,CLERK.PAYROLL,PUB on LDEV 26 streams the file
UPDATE.PUB.PAYROLL; then, the first three lines of the generated job stream
will be:

   :COMMENT   STREAM FILE UPDATE.PUB.PAYROLL
   :COMMENT     STREAMED BY JOAN,CLERK.PAYROLL,PUB ON LDEV 26
   :COMMENT    ON MON, SEP 14, 1988,  5:19 PM

These lines will show up in the job $STDLIST, so if you either print it or look
at it in the spooler, you'll be able to know exactly which file was being
streamed and exactly who streamed it.

This is both a useful auditing device -- if you look at a job stream, you can
see who was responsible for streaming it -- and a good debugging tool, since
just by looking at a $STDLIST you can find out what STREAMX "smart job stream"
might have generated it.

-- CHANGING ?, , AND  CHARACTERS


Changing ?, and characters ``contents
Changing ?,  and  characters


?, (STREAMX delimiter) changing it
, (STREAMX delimiter) changing it
::SETQUESTION, STREAMX stream-time command
::SETBRACES, STREAMX stream-time command
, you may want to embed ?, , and  characters into your stream files
WITHOUT having STREAMX interpret them specially.  Some of your programs might,
for instance, want ?s, s, and s as input or you might want to execute an MPE
command that involves some of these characters (e.g.  :LISTF AP???X).

For this reason, STREAMX lets you change the question delimiter character
(which is by default "?") and the expression delimiter characters (default ""
and "") to anything you please.  Thus, you might say:

   ::SETQUESTION `
   ::SETBRACES []
   !TELLOP beginning
   !LISTF AP???X
   !RUN MYPROG
   ` Department`
   [1+2]

the first three lines after the "::" commands ("!LISTF AP???X", "!TELLOP
beginning" and "!RUN MYPROG") would be copied into the job stream verbatim
and the next two ("` Department`" and "[1+2]") would prompt the user with
"Department?" and evaluate the expression "1+2", respectively.


VESOFTQUESTIONDELIMITER, STREAMX JCW ``question`delimiter
VESOFTQUESTIONDELIMITER, STREAMX JCW
VESOFTOPENBRACE, STREAMX JCW
VESOFTCLOSEBRACE, STREAMX JCW
may also set the three JCWs  VESOFTOPENBRACE, VESOFTCLOSEBRACE, and
VESOFTQUESTIONDELIMITER to the ASCII values of the characters you want to use
for the brace or question replacements.  For instance,

   :SETJCW VESOFTQUESTIONDELIMITER = 126
   :SETJCW VESOFTOPENBRACE = 91
   :SETJCW VESOFTCLOSEBRACE = 93

will set the question delimiter to "~" (ascii 126), the open brace character to
"[" (ascii 91), and the close brace character to "]" (ascii 93).

These JCWs will remain in effect for all the files you stream in your session,
until you reset the JCWs or log off.  If you put the appropriate :SETJCW
commands into your SECURCON file (using $LOGON-EXCUTE keyword), the settings
will take effect for all the files you stream in your system.

Finally, you might also just say

   ::SETQUESTION
   ::SETBRACES

which will turn off question and expression evaluation processing altogether.
Then, you can use any characters you please without having STREAMX treat any of
them specially; when you want to be able to specify questions and expression
evaluators again, you can just issue another ::SETQUESTION or ::SETBRACES
command to redefine the question and brace characters (e.g.  "::SETQUESTION ?"
and "::SETBRACES ").

-- INCREASING THE NUMBER OF STREAMX VARIABLES YOU CAN HAVE


Increasing the number of STREAMX variables you can have ``contents
Increasing the number of STREAMX variables you can have

Whenever you create a new STREAMX variable -- by ::ASSIGNing to it or
::PROMPTing for it -- STREAMX has to allocate room for it.  By default, we
allocate a 4096-word "variable area" in which all the variables (in a job
stream and any job streams that it invokes) are kept.  Each string variable
uses slightly over 128 words; integer and date variables use much less.

At the default 4096 words, the variable area has room for about 28 string
variables.  If you want to have more variables, you can, for instance, say


STREAMXVARAREASIZE, JCW: sets maximum # of STREAMX variables

     :SETJCW STREAMXVARAREASIZE = 8192   << or any such number >>

This :SETJCW indicates that the variable area should be 8192 words long, thus
having room for about twice as many variables.

What's the cost of this? Well, STREAMX has only so much room in its stack.
Parsing complicated expressions (e.g.  in ;CHECK=s, xxx constructs, etc.)
takes up a good deal of stack space; nested job stream files (file A streams
file B which streams file C, etc.) take up stack space, too.

The higher you set STREAMXVARAREASIZE, the fewer stream files can be nested,
and the more the chances that some complicated expression will cause a stack
overflow (especially if it's nested pretty deeply in your stream files).


Error message: "Variable area overflow"
a rule, you should leave STREAMXVARAREASIZE at the default (4096) until you
run out of room (you'll get an error message saying "Error: Variable area
overflow").  Then, you can increase it, but not by too much, especially if you
use a lot of nested job stream files.

-- GLOBALLY SETTING JOB CARD PARAMETERS


Globally setting job card parameters ``contents
Globally setting job card parameters


JOBPARMS-DEFAULT, STREAMX configuration keyword
$JOBPARMS-DEFAULT, STREAMX configuration keyword
allows you to set either default or mandatory job card parameters (e.g.
OUTCLASS, INPRI, etc.) on a global basis instead of just on each job card.
This lets you, among other things:

   * Easily change the way that many jobs are submitted, without having to
     modify each one.  For instance, if you've decided that all the jobs that
     log on into the AP account should, by default, run in ES priority, you can
     add the following line to your STREAMX.DATA.VESOFT file:

       $JOBPARMS-DEFAULT @.@ @.@.@ @.AP "PRI=ES"

     Note that the first three parameters are the same as the $NOPASS keyword's
     parameters -- the streaming user userset (here @.@), the job stream
     mpefileset (here @.@.@), and the job stream userset (here @.AP).

   * Change the way that a job is submitted by a third-party package that
     builds the job itself and thus doesn't normally let you change the !JOB
     card parameters.  For example, if you know that a particular package
     builds a stream file called JOBFILE.DATA.GL, and you want to have this job
     run with OUTCLASS=,1 (i.e.  output priority 1), you can just say

      $JOBPARMS-DEFAULT @.@ JOBFILE.DATA.GL @.@ "OUTCLASS=,1

     Note: to use this feature, you will have to patch the third-party software
     to use STREAMX instead of STREAM.  As documented earlier (see "What If
     Your Program Does A :STREAM Programmatically (With The COMMAND
     INTRINSIC)"), this is very easy to do.


JOBPARMS-ALWAYS, STREAMX configuration keyword
$JOBPARMS-ALWAYS, STREAMX configuration keyword

  * Require jobs launched by certain users to run with, say, a lower run-time
     priority or input priority.  For instance, if you want to make sure that
     all jobs streamed by people in the TEST account run with PRI=DS and
     INPRI=3, you can say

       $JOBPARMS-ALWAYS @.TEST @.@.@ @.@ "PRI=DS;INPRI=3"

     Note that this uses the $JOBPARMS-ALWAYS keyword, which adds the
     parameters to the job card regardless of whether the job card already
     contains these parameters -- the $JOBPARMS-DEFAULT keyword parameters can
     be overridden by parameters specified on the job card.

If both a $JOBPARMS-DEFAULT and a $JOBPARMS-ALWAYS apply, the $JOBPARMS-ALWAYS
takes effect, whether it comes first in the STREAMX.DATA file or not.

What happens if more than one $JOBPARMS-DEFAULT applies to the same job?
STREAMX uses the first $JOBPARMS-DEFAULT in the STREAMX.DATA file for each job
parm.  (Likewise, if more than one $JOBPARMS-ALWAYS applies to the job, STREAMX
uses the first one.) For example, if your STREAMX.DATA file contained the
following:

   $JOBPARMS-DEFAULT KIMBERLY,MGR.PR  @.JOB.PR  @.PR  "OUTCLASS=LJ"
   $JOBPARMS-DEFAULT KIMBERLY,MGR.PR  @.JOB.PR  @.PR  "INPRI=2"

then the job would be streamed with both ;OUTCLASS=LJ and ;INPRI=2.

$DEFINE-USERSET


DEFINE-USERSET usable in STREAMX.DATA``contents`news
$DEFINE-USERSET usable in STREAMX.DATA

In addition to the SECURCON file, the $DEFINE-USERSET keyword may be used in
the STREAMX.DATA configuration file.  The usage is the same as for the SECURCON
file, i.e.

   $DEFINE-USERSET varname userset.accountset [...]

to define a userset, and

   $NOPASS            !varname fileset target-logon [$NOLOCK fileset]
   $NO-FILE-SEC-CHECK !varname fileset
   $WITHCAPS-PERMIT   !varname fileset capset
   $CHLOGON-PERMIT    !varname fileset target-chlogon

to invoke the userset as needed.  Note that the defined userset may only be
used as a source userset, not as a target of a $CHLOGON or $NOPASS keyword.


Scheduling STREAMX jobs to repeat``contents`news
Scheduling STREAMX jobs to repeat

Syntax:   :STREAM filename
                   [;REPEAT= [DAILY|WEEKDAYS|day of week[, ...] ]
                   [;WHENEVER= condition]
                   [;WHEN= condition]
                      [;CHECKEVERY= minutes| DAILY ]
                   [;MPE SCHED PARMS]

Examples:  These examples show how to...

   ...stream a job at a scheduled time each day:

       :STREAM MAINJOB ;REPEAT=DAILY ;AT=01:00

   ...stream a job several times each day (once each hour):

       :STREAM XPMAIL.MAILJOB.SYS;&
                WHENEVER=(BETWEEN(HPHOUR,6,17) and (HPMINUTE=0))

   ...stream a job once a month:

       :STREAM REPORT.JOB.SYS;WHENEVER=(hpdate=1);CHECKEVERY=DAILY

   ...stream a job if another job fails (aborts):

       :STREAM RECOVER.JOB.SYS; WHEN=JSCOUNT('POST,MGR.PAYROLL')=0

We have added additional keywords that STREAMX will recognize when using our
supplied UDC for STREAM/STREAMX.  These keywords allow you to schedule jobs
that repeat on a regular basis or when a particular event occurs.  If you
include any of the keywords ;REPEAT, ;WHEN or ;WHENEVER on a stream command,
STREAMX will schedule the job using the %BACKG ALARM task.  In addition to
using these keywords on the command line, they may be used in a STREAMX
::SETSCHEDULE command as well.


VESOFTDOALLSCHED, JCW to force STREAMX to use %BACKG sched.
scheduled with a REPEAT, WHEN or WHENEVER condition are displayed by the
MPEX %SHOWSCHED command as well as in a separate section of the MPEX %SHOWJOB
command.  Jobs scheduled with just the MPE scheduling parameters of IN, DAY, or
DATE do not show up in the %SHOWSCHED command (of course, the MPE and MPEX
SHOWJOB command will show scheduled jobs that do not repeat).  If you want to
force all jobs to be submitted by our background task so they show up in the
%SHOWSCHED command (and in the same area of the %SHOWJOB command), set the JCW
VESOFTDOALLSCHED to 1 before using the STREAM or STREAMX UDC.


REPEAT=, STREAMX scheduling keyword``news
REPEAT=, STREAMX scheduling keyword
the ;REPEAT= option, you can use the keywords DAILY for every day of the
week, WEEKDAY for every "work" day (excludes Saturday and Sunday), a specific
day of the week or a list of days.  For specific days, you need to supply at
least the first three letters of the each day you want the job streamed.

Ordinarily, when you use the ;REPEAT= keyword, you would also use ;AT= to
specify a particular time each day that the job should be streamed.  If you use
;REPEAT= without ;AT=, the scheduled time for the jobs to repeat will be the
time of day that you issued the command.  So if you type:

    :STREAM SCHEDJOB;REPEAT=MON,WED,SAT

at 4:08 in the afternoon, then this job will be scheduled to execute at 4:08PM
on Monday, Wednesday and Saturday.


WHEN=, STREAMX scheduling keyword``news
WHEN=, STREAMX scheduling keyword
WHENEVER=, STREAMX scheduling keyword
keywords ;WHEN and ;WHENEVER are used to specify a condition that when true
will launch the job.  ;WHEN is used to set up a single event jobstream -- when
the condition becomes TRUE, the job is streamed and deleted from the scheduler.
;WHENEVER is used to set up a multiple event jobstream -- as long as the
condition is TRUE, the job will be launched.  To avoid streaming several jobs
at once if the condition remains TRUE for a long time (e.g.  if the condition
is based upon whether or not a particular user is logged on) STREAMX will not
launch another copy of the job if the previous job is still active.


CHECKEVERY=, STREAMX scheduling keyword``news
CHECKEVERY=, STREAMX scheduling keyword
STREAMX scheduler uses the %BACKG ALARM task to schedule, test and submit
jobs, so the STREAMX parameter of ;CHECKEVERY has the same effect as the %ALARM
parameter of ;CHECKEVERY.  This keyword causes the ALARM task to test the
condition less often -- after the condition is tested, the next CHECKEVERY
intervals are skipped before the condition is tested again.

In one of the examples above, the condition being tested is:

     BETWEEN(HPHOUR,6,17) and (HPMINUTE=0)

Since the default is to test the condition once each minute, this will be TRUE
if the time of day is between 6:00 AM and 5:00 PM - AND - if the minute of the
hour is 0 (every hour, "on the hour").  If you didn't care exactly WHEN during
the hour that the job streams, but you want the job to be streamed AT LEAST
once each hour, you could use:

    :STREAM XPMAIL.MAILJOB.SYS;&
             WHENEVER=BETWEEN(HPHOUR,6,17);CHECKEVERY=60

To review, you would use:

   ;REPEAT and ;AT to repeat a job at a particular time every day of the week
     or on specific days.

   ;WHEN to launch a job if and when a particular event occurs.

   ;WHENEVER to launch a job as long as the condition is true.

   ;CHECKEVERY to reduce the number of times the condition is tested each day.

The current job schedule may be viewed using the %SEC SHOWSCHED command
(similar to MPEX's %SHOWALARM).  Jobs that are displayed in this list may be
removed with the %SEC ABORTJOB command, which is equivalent to %DELETEALARM.

-- MISCELLANEOUS


STREAMX: Miscellaneous ``contents
STREAMX: Miscellaneous


STREAMXJOBNUMBER, JCW set to job number of streamed job

  * Whenever you stream a job with STREAMX, we will set a JCW called
     STREAMXJOBNUMBER to the job number of the submitted job.  You can then use
     that job number to, perhaps, do an automatic :SHOWJOB to see what the job
     state is or to somehow log the job submission information or whatever.

     If more than one job was streamed by this execution of STREAMX,
     STREAMXJOBNUMBER will contain the job number of the last job streamed.


VECURRFILENAME, variable set to the streamed job filename
VECURRFILENAME, variable set to the ::USE filename
VECURRFILENAME, variable set to the menu filename
VECURRFILENAME, variable set to the command filename

  * The variable VECURRFILENAME contains the filename of the job currently
     being processed by STREAMX.  This could be the job file you actually
     :STREAMed, a "::USE" file or the name of a "nested" job that your job
     :STREAMs, depending on where you access it.

     In a menu (see "Logon Menus", above), this variable will contain the name
     of the menu file.

     In a command file, this variable will contain the name of the command
     file.


Introduction: Unattended terminal security ``contents`logoff
Introduction: Unattended terminal security

People often remain logged on to the computer even when they're not actively
using it.  This can cause several problems:

   * Security: Unattended terminals can be a grave security threat.  An
     unattended logged-on terminal can defeat the best security system; anybody
     can come up and use it without having to re-logon and specify any
     passwords.

     Say one of your accountants goes to lunch without logging off -- now
     somebody else can walk up, add vendors, enter invoices, print checks, what
     have you; not only won't he have to answer any passwords, but all the
     audit trails will point to the original user, not the unauthorized
     interloper!

     Another example: on some systems, if a user "hangs up" on a modem
     connection without first saying BYE, the next user to dial-in to that port
     is simply dropped into the first user's session, without having to enter
     any passwords! (This can be avoided with a simple configuration change on
     most, but not all systems.)

     This is a very serious issue indeed, and is one reason why most computer
     systems have automatic logoff of idle sessions as part of their standard
     operating systems.

     (Note: also see the chapter on "Allowing A User To Lock Up His Terminal
     Before Leaving It Unattended" in the LOGON SECURITY section).

   * Networking: If you have a local area network, unattended terminals can
     waste precious ports.  Ports are often scarce since each one of them costs
     a good deal of money to configure on your computer; idle sessions can
     greatly aggravate port contention problems.

     Some networks have an "idle session abort" facility, but they measure
     idleness by whether any data has recently been passed between the computer
     and the terminal.  If somebody's busy running some big report that does no
     terminal I/O, he'll get aborted even though he's by no means idle -- not a
     good thing!

   * Operations: At the end of the day, many people's sessions remain logged
     on, making backups difficult.  Almost everybody's gone home, but there are
     10 sessions still logged on.  To do the backup, you have to abort
     everybody, a time-consuming process -- and what if somebody's still
     working?

     You'd like to make sure that all idle sessions are aborted (but all the
     active sessions should remain so that you can talk to each individually
     and get them to log off in an orderly fashion).

   * System resources.  Each session uses a good number of system table entries
     (DSTs, PCBs, etc.) and virtual memory.  Sites that are running into system
     table limits are often the victims of users who consume system resources
     even though they're not actively using the computer.

What does LOGOFF do? It lets you

   ABORT SESSIONS THAT HAVE BEEN IDLE FOR A GIVEN AMOUNT OF TIME.

In particular, LOGOFF

   * Lets you select which terminals, which users, and which programs are to be
     logged off.

   * Lets you specify different maximum idle intervals for different terminals,
     users, and programs.

   * Properly unlocks any block mode terminals that are being aborted.

   * Aborts only those sessions that actually have a terminal I/O pending (with
     a few exceptions, mentioned below).

   * Aborts all sessions using normal MPE :ABORTJOB, so all open files,
     databases, etc.  are closed correctly.

   * Lets you see (online) the current activity status of all sessions in the
     system.

We think that you'll find LOGOFF to be a very flexible and powerful tool for
the security and operating convenience of your system.

Running LOGOFF

LOGOFF executes as a task under the BACKG job -- to start it, just do a

   %SEC BACKG STARTJOB        (* If it's not already running *)
   %SEC BACKG START,LOGOFF

(Please see %BACKG in the MPEX Commands chapter of the MPEX User Manual for
details.)

LOGOFF gathers information on the state of the current system and then goes to
sleep.  Some time later (5 minutes, by default) it wakes up and looks around
again; whenever it notices a session that's been idle for more than a given
amount of time (we'll tell you how to configure this shortly), LOGOFF aborts
that session.

LOGOFF continues running like this, pausing and re-awakening, until you stop it
via the %BACKG STOP,LOGOFF command (or you stop the BACKG job itself).

LOGOFF gets its configuration information from a file that you must build
called LOGOFF.DATA.VESOFT.  A very simple example might be:


LOGOFF.DATA.VESOFT, LOGOFF configuration file

   :HELLO MANAGER.VESOFT
   :EDITOR
   /ADD
       1    $TIMEOUT 600
       2    //
   /KEEP LOGOFF.DATA.VESOFT,UNN; EXIT

Here LOGOFF.DATA.VESOFT is built with only one record, a $TIMEOUT.  "$TIMEOUT
600" indicates that sessions are to be aborted after 10 minutes (600 seconds)
of idleness.  All sessions, regardless of which terminal they're on, which user
they belong to or which program they're running, will be aborted (this is the
default, but may be modified).

A slightly more complicated example might have the LOGOFF.DATA.VESOFT file
looking like:

   $TIMEOUT 900
   $USERS INCLUDE @.AP @.GL CLERK.PAYROLL
   $TERMINALS EXCLUDE 21 22 35 52
   $PROGRAMS EXCLUDE MASTER00.PUB.AP QUERY.PUB.SYS
   $MESSAGE "** ABORTED DUE TO LACK OF ACTIVITY **"

This indicates that after 15 minutes of idleness, all sessions

   * that are logged on either in the AP account (@.AP), GL account (@.GL) or
     as the user CLERK.PAYROLL

   * and are not on terminals 21, 22, 35 or 52

   * and are not running the programs MASTER00.PUB.AP or QUERY.PUB.SYS

will be aborted.  When they're aborted, they'll be sent the message "** ABORTED
DUE TO LACK OF ACTIVITY **".

An even fancier example is:

   $MESSAGE "** ABORTED DUE TO LACK OF ACTIVITY **"
   $TIMEOUT 600
      $USERS INCLUDE @.PAYROLL
      $PROGRAMS INCLUDE @.PUB.PAYROLL QUERY.PUB.SYS
   $TIMEOUT 1500
      $USERS EXCLUDE JACK,@.@ PETE,@.@
      $TERMINALS EXCLUDE 23 27
   $TIMEOUT 300
      $USERS EXCLUDE JACK,@.@
      $SELECT "NOT BETWEEN (CLOCK, 8AM, 6:15PM)"

This aborts

   * After 10 minutes ($TIMEOUT 600) of idleness, all sessions
     -      that are logged on to the PAYROLL account (@.PAYROLL)
     - and are running a program in PUB.PAYROLL or QUERY.PUB.SYS.

   * After 25 minutes ($TIMEOUT 1500) of idleness, all sessions
     - except those whose session names are JACK or PETE
     - and also except those on terminals 23 and 27.

   * Between 6:15 PM and 8:00 AM only, after a mere 5 minutes ($TIMEOUT 300) of
     idleness, all sessions
     - except those whose session name is JACK.

Note that in all three cases, the message sent to the terminal before the abort
will be "** ABORTED DUE TO LACK OF ACTIVITY **".  Note how the things that
immediately follow a $TIMEOUT apply only to that timeout period, but the things
that precede all $TIMEOUTs (in this case, $MESSAGE) apply equally to
everything.

Note that LOGOFF doesn't care about multiple spaces or about line breaks;

   $TIMEOUT 10 $TERMINALS INCLUDE 20 21 23 $USERS EXCLUDE JACK,@.@

and

   $TIMEOUT
     10
   $TERMINALS
     INCLUDE
     20
     21
     23
   $USERS
         EXCLUDE
   JACK,@.@

are identical.  The only places in which LOGOFF cares about spaces are between
tokens (i.e.  "202123" is not the same as "20 21 23") and in quoted strings.


Configuring LOGOFF: who is to be aborted ``contents
Configuring LOGOFF: who is to be aborted

By default, LOGOFF will abort

   * all sessions (except for the console)

   * that have been completely idle (i.e.  used no CPU time)

   * in the past $TIMEOUT period

   * and have a terminal read pending.

The LOGOFF.DATA.VESOFT file lets you restrict and modify this in virtually any
way you like.

Note: if a user is included in one keyword in a particular $TIMEOUT section and
excluded in another keyword in the same $TIMEOUT section, the user will not be
aborted.  Basically, within a particular $TIMEOUT section, LOGOFF looks for any
reason not to abort a user, and then stops checking that user.

On the other hand, if a user is included in one $TIMEOUT section, but excluded
in another $TIMEOUT section, he will be aborted.  This is so you can configure
LOGOFF to abort some users only under certain circumstances; for example, you
may want to abort users after 1 hour of inactivity during the day, and after 15
minutes at night.

The keywords you can specify in LOGOFF.DATA.VESOFT to indicate who you want
aborted are:


TIMEOUT, LOGOFF configuration keyword
$TIMEOUT, LOGOFF configuration keyword

   $TIMEOUT numseconds
   e.g.  $TIMEOUT 900

         Indicates how long a session may be idle before it's aborted.


TERMINALS INCLUDE, LOGOFF configuration keyword
$TERMINALS INCLUDE, LOGOFF configuration keyword

   $TERMINALS INCLUDE ldev1 ldev2 ldev3 ...  ldevN
   e.g.  $TERMINALS INCLUDE 60 61 62 63 65 67 74

         Tells LOGOFF to abort only sessions that use the given terminals.  At
         most 98 terminals can be specified.


TERMINALS INCLUDE with device classes
$TERMINALS INCLUDE with device classes

        You may also specify device classes in the $TERMINALS INCLUDE (and
         EXCLUDE) lists, e.g.

            $TERMINALS INCLUDE 25 27 REMTERMS 55 DSTERMS 99

         -- this will include terminals 25, 27, 55, 99 and all terminals in the
         device classes REMTERMS and DSTERMS.  However, the limit of at most 98
         terminals overall still applies.


TERMINALS EXCLUDE, LOGOFF configuration keyword
$TERMINALS EXCLUDE, LOGOFF configuration keyword
$TERMINALS INCLUDE/EXCLUDE limited to 98 devices

   $TERMINALS EXCLUDE ldev1 ldev2 ldev3 ...  ldevN
   e.g.  $TERMINALS EXCLUDE 21 22 29

         Tells LOGOFF to abort all sessions except those that use one of the
         given terminals.  As noted above, you may used device classes with
         either $TERMINALS INCLUDE or EXCLUDE instead of LDEV numbers.

         Of course, you may use either $TERMINALS INCLUDE or $TERMINALS EXCLUDE
         (or neither), but not both.  In either case, however, the total number
         of devices INCLUDED or EXCLUDED is limited to 98.


USERS INCLUDE, LOGOFF configuration keyword
$USERS INCLUDE, LOGOFF configuration keyword

   $USERS INCLUDE usersets
   e.g.  $USERS INCLUDE @.PAYROLL TEST.DEV,UTIL X???@,@.@

         Tells LOGOFF to abort only those sessions that match one or more of
         the given user IDs.  The "usersets" are of the same format as the
         usersets that can be specified in the SECURCON.DATA.VESOFT file (see
         the Usersets chapter in this manual); some examples are:

              @.PAYROLL              (user.account)
              JACK,@.@               (session,user.account)
              X@,CLERK.PAYROLL,PUB   (session,user.account,group)
              @.SYS-MANAGER.SYS      (userset-userset, indicating
                                       all SYS users except MANAGER.SYS)
              @.AP+@.GL-JACK,@.@-PETE,@.@
                                     (userset+userset-userset-userset;
                                       all AP/GL users except those
                                       with session name JACK or PETE)


USERS EXCLUDE, LOGOFF configuration keyword
$USERS EXCLUDE, LOGOFF configuration keyword

   $USERS EXCLUDE usersets
   e.g.  $USERS EXCLUDE @.TELESUP JACK,@.@ PETE,@.@ MANAGER.SYS

         Tells LOGOFF to abort all sessions except those that match one or more
         of the given user IDs.  The rules for each userset are the same as
         those for $USERS INCLUDE.  Of course, you may use either $USERS
         INCLUDE or $USERS EXCLUDE (or neither), not both.


PROGRAMS INCLUDE, LOGOFF configuration keyword
$PROGRAMS INCLUDE, LOGOFF configuration keyword

   $PROGRAMS INCLUDE mpefileset1 mpefileset2 ...  mpefilesetN
   e.g.  $PROGRAMS INCLUDE QUERY.PUB.SYS @.PUB.PAYROLL

         Tells LOGOFF to abort only those sessions whose "currently running
         program" is included in one or more of the given mpefilesets.  Since
         LOGOFF normally aborts only those sessions that have a terminal read
         pending (with a few user-configurable exceptions, see below), the
         "currently running program" is the one that issued the read.


MPE/V and MPE/iX differences: LOGOFF $PROGRAMS INCLUDE CI

        In other words, if a user runs a main menu program called
         PR000.PUB.PAYROLL which then process-handles to a son process called
         PR150X.PUB.PAYROLL, and the son process issues the terminal read, the
         "currently running program" will be PR150X.PUB.PAYROLL.  If you want
         to include sessions where the active process is the Command
         Interpreter, specify a fileset of "C.I." (on MPE/iX systems,
         "CI.PUB.SYS").


PROGRAMS EXCLUDE, LOGOFF configuration keyword
$PROGRAMS EXCLUDE, LOGOFF configuration keyword

   $PROGRAMS EXCLUDE mpefileset1 mpefileset2 ...  mpefilesetN
   e.g.  $PROGRAMS EXCLUDE @.UTIL.DEV  EDITOR.PUB.VESOFT

         Tells LOGOFF to abort all sessions except those whose currently
         running program is in one of the specified mpefilesets.  Of course,
         you may use either $PROGRAMS INCLUDE or $PROGRAMS EXCLUDE (or
         neither), not both.


SELECT, LOGOFF configuration keyword
$SELECT, LOGOFF configuration keyword
Backups, making them easier with LOGOFF
Activating LOGOFF at a certain time

   $SELECT "condition"
   e.g.  $SELECT "BETWEEN (CLOCK, 6PM, 6:30PM)"

         Tells LOGOFF to abort sessions only if the given condition (a logical
         expression of the kind described in the Appendix of this manual) is
         TRUE.

         This can be very useful for, say, making LOGOFF run only during
         certain hours:

               $SELECT "BETWEEN (CLOCK, 6PM, 6:30PM)"

         Here the expression "BETWEEN(CLOCK,6PM,6:30PM)" is evaluated; CLOCK,
         an expression function (see Appendix) returns the current time of day,
         and the time is checked by BETWEEN to see if it's between 6 PM and
         6:30 PM.  If it is, LOGOFF will be active; if not, LOGOFF will go to
         sleep until the $SELECT condition is met.

         A more sophisticated example might be

               $SELECT "BETWEEN (CLOCK, 6PM, 6:30PM) AND &
                        BETWEEN (HPDAY, 2, 5) or &
                        BETWEEN (CLOCK, 5PM, 5:45PM) AND HPDAY=6"

         This causes LOGOFF to be active from 6 PM to 6:30 PM on Monday through
         Thursday (2<=HPDAY<=5) OR from 5 PM to 5:45 PM on Friday (HPDAY=6).
         Note that we use a "&" continuation character to split the selection
         condition over multiple lines.

         Finally, one more example: say that you are using LOGOFF to minimize
         port contention on your data switch.  You might say:

               $SELECT "HPSESCOUNT > 40"

         This means that LOGOFF will only become active when more than 40
         sessions are logged on.

         Again, for more details on the syntax of the condition, see Appendix.


DSABORT, LOGOFF configuration keyword
$DSABORT, LOGOFF configuration keyword
$NODSABORT, LOGOFF configuration keyword

   $DSABORT
   $NODSABORT

         $DSABORT tells LOGOFF to abort all sessions including those that are
         using DS (either sessions logged on from another computer or those
         logged on to another computer and using this computer as a host).
         $NODSABORT tells LOGOFF to EXCLUDE such DS sessions.

         The default is $NODSABORT, largely because aborts of DS host or slave
         sessions can sometimes fail and create "ghost sessions" (due to
         glitches in DS/3000).  However, feel free to try specifying $DSABORT
         -- it might very well work on your version of DS/3000.


LANABORT, LOGOFF configuration keyword
$LANABORT, LOGOFF configuration keyword
$NOLANABORT, LOGOFF configuration keyword

   $LANABORT
   $NOLANABORT

         $LANABORT tells LOGOFF to abort all sessions including those that are
         using LAN/3000 (either sessions logged on FROM or TO another
         computer).  $NOLANABORT tells LOGOFF to EXCLUDE such LAN sessions.

         The default (mostly for historical reasons) is $LANABORT.  We don't
         foresee any problems with this setting, but make the other available
         to you in case you find that your version of LAN/3000 doesn't handle
         :ABORTJOBs well.


CPUTHRESHOLD, LOGOFF configuration keyword ``threshold
$CPUTHRESHOLD, LOGOFF configuration keyword

   $CPUTHRESHOLD numseconds
   e.g.  $CPUTHRESHOLD 1
     or $CPUTHRESHOLD 0.15

         By default, LOGOFF aborts sessions only if they haven't used any CPU
         time during the idle period specified by a $TIMEOUT.  One input
         transmission (sent to the computer by a carriage return or enter), one
         output from the program, one millisecond of calculation -- any of
         these is enough to save the session from being aborted.  This is
         usually OK, since it indicates that the terminal isn't really idle or
         unattended.

         However, some programs (e.g.  HPWORD or HPDESK) periodically wake up,
         do some tiny amount of processing (e.g.  check mailbox status), and go
         back to waiting for terminal input.  There doesn't have to be any user
         interaction for this to happen -- the programs do this periodic
         processing on their own, so though they're accruing CPU time, the
         terminal may indeed be unattended.

         If you set $CPUTHRESHOLD, a session will be aborted if it's used less
         than the threshold number of CPU seconds in the past $TIMEOUT period.
         Thus, saying "$CPUTHRESHOLD 0.5" and "$TIMEOUT 900" tells LOGOFF to
         abort all sessions that have used 0.5 or less seconds in the past 15
         minutes.  This should prevent aborting any truly active sessions, but
         may still manage to catch those whose only activity has been
         automatic.

         As the examples show, the number of seconds may be a real number (e.g.
         0.25) -- this is the only keyword that allows real numbers.  The
         $TIMEOUT, $PAUSETIME and $WARNTIME values must be integers.


ABORTNOWAITIO, LOGOFF configuration keyword ``nowait
$ABORTNOWAITIO, LOGOFF configuration keyword

   $ABORTNOWAITIO

         By default, LOGOFF aborts only those processes that are waiting for a
         normal terminal I/O.  A few programs (such as IMF and TELAMON's
         Network Engine) issue "no-wait I/O"s to the terminal, and are thus not
         normally caught.

         $ABORTNOWAITIO says that LOGOFF should abort sessions that are doing
         either a normal I/O or a no-wait I/O.


MPE/V and MPE/iX differences: $ABORTNOWAITIO in LOGOFF

        This keyword does not work on MPE/iX systems.


ABORTMSGWAIT, LOGOFF configuration keyword
$ABORTMSGWAIT, LOGOFF configuration keyword

   $ABORTMSGWAIT

         As we said above, LOGOFF normally aborts only those processes that are
         waiting for a terminal I/O (since a session can quite legitimately
         wait for a long time for, say, a :REPLY, a message file, a PAUSE, etc.
         without being really idle).

         However, sometimes you may also want to abort processes that are
         waiting for a message file I/O -- one case in which this may happen is
         for DS/3000 host sessions.  By specifying $ABORTMSGWAIT, you tell
         LOGOFF to abort sessions that are waiting for message file I/O
         (assuming, of course, that they've been idle for the $TIMEOUT number
         of seconds).


MPE/V and MPE/iX differences: $ABORTMSGWAIT in LOGOFF

        This keyword does not work on MPE/iX systems.

When LOGOFF.PUB.VESOFT is run, it opens LOGOFF.DATA.VESOFT, reads it, and keeps
it open.  If you want to change LOGOFF.DATA.VESOFT, just stop LOGOFF (using
%BACKG STOP,LOGOFF), make the changes, and re-start LOGOFF (%BACKG
START,LOGOFF).


Configuring LOGOFF: what happens at abort time ``contents
Configuring LOGOFF: what happens at abort time

By default, when a session is being aborted, it is sent the message "LOGOFF: **
ABORTED DUE TO LACK OF ACTIVITY **".  This message appears on the user's screen
before the "SESSION ABORTED BY SYSTEM MANAGEMENT", thus letting the user know
what happened.


MESSAGE, LOGOFF configuration keyword
$MESSAGE, LOGOFF configuration keyword
you want to change the message, no problem: just add a line saying

   $MESSAGE "text"

to the LOGOFF.DATA.VESOFT file.  For instance, you might say

   $MESSAGE "IN THE FUTURE, PLEASE LOG OFF WHEN NOT USING TERMINAL!"

and then the given message will be sent to each session before its logged off.
(After all, your goal is to get people to log off when they're not using their
terminals; in fact, many of our customers find that the longer they run LOGOFF,
the fewer sessions get aborted every day -- users learn to :BYE off themselves
when they're not using the computer.)


NOBLOCK, LOGOFF configuration keyword ``block
$NOBLOCK, LOGOFF configuration keyword
case a user's terminal is in block mode, LOGOFF always prefixes the message
with some escape sequences that should get the terminal out of block mode and
whatever other special modes have been set.

This should usually work quite well, but sometimes it may not be what you want
(for instance, if you have non-HP terminals which do strange things when they
receive HP escape sequences).  If you don't want LOGOFF to send the
get-out-of-block-mode escape sequences, just add the

   $NOBLOCK

keyword to the LOGOFF.DATA.VESOFT file.  If the $NOBLOCK keyword is present,
LOGOFF will send only the $MESSAGE text (rather than the escape sequences
followed by the $MESSAGE text).


NOSOFTRESET, LOGOFF configuration keyword ``terminal`reset
$NOSOFTRESET, LOGOFF configuration keyword
Escape sequences used by LOGOFF
escape sequences that LOGOFF sends are actually quite interesting.  These
standard escape sequences include:

   * "<ESCAPE> X" to turn off format mode,

   * "<ESCAPE> F" to send the cursor to the bottom of the screen,

   * "<ESCAPE> &k0B" to turn off block mode,

   * "<ESCAPE> &jR" to unlock the terminal's function keys,

   * "<ESCAPE> g" to do a SOFT RESET (needed to reset some keyboard lock
     conditions),

   * and 20 control-F's used as fillers to take up some time after the SOFT
     RESET (since the soft reset tends to make the terminal unable to accept
     any characters for several milliseconds).

The first four of these escape sequences are quite necessary in order to
properly get terminals out of block mode; the next two, though (the SOFT RESET
and the 20 control-F's), are sometimes necessary but at other times have some
unpleasant side effects:


Lost characters in LOGOFF $MESSAGE, how to avoid

  * On occasion, you may find that the first several characters of your
     $MESSAGE text get lost.  This is because of the SOFT RESET temporarily
     disabling the terminal -- sometimes the 20 pad characters we send after it
     don't take enough time for the terminal to become ready again.


Split $MESSAGE line in LOGOFF, how to avoid

  * You may also find the $MESSAGE text being split in the middle.  This is
     because the HP procedure we use to send the message splits the text being
     sent at the 80th character (since some old terminals didn't properly wrap
     around lines that were more than 80 characters long); unfortunately, it
     doesn't realize that the first 30 or so characters are unprintable, so it
     may end up splitting the printable text at about its 40th or 50th
     character.

   * Depending on which terminal you use (and how it's configured), the soft
     reset may do too much; in particular, it might reset the CAPS LOCK flag
     (if the terminal isn't configured with CAPS LOCK ON).

These problems are the exception rather than the rule; however, if you
encounter them, you might want to add a

   $NOSOFTRESET

to your LOGOFF.DATA.VESOFT file.  This prevents LOGOFF from sending the SOFT
RESET and the 20 control-F's.  This may very well be better for you than the
default way LOGOFF does things.


TERMUNLK.JOB.VESOFT ``unlocking`terminals
TERMUNLK.JOB.VESOFT
, LOGOFF's normal "get-out-of-block-mode" escape sequences are quite
enough for properly resetting the terminal that's being aborted.  Sometimes
(we're not quite sure when -- on some systems, this happens often, but on
others never), MPE manages to put the terminal back into block mode before the
session is actually aborted.  Apparently what happens is that after we get the
terminal out of block mode and do the :ABORTJOB, the session isn't immediately
aborted; rather, it hangs around for a few more seconds, during which time it
undoes all the escape sequences that we sent it!

If you find yourself facing this problem, we recommend that you stream the job
stream TERMUNLK.JOB.VESOFT.  This job stream goes into your system message
catalog file and modifies the "CPU=... CONNECT=..." message that gets output at
the end of each session to also include the "get terminal out of block mode"
escape sequences.  Thus, even if the terminal somehow manages to get back into
block mode before the session is aborted, the escape sequences in the
"CPU=... CONNECT=..." message will get it to back to a normal state.

Note that there's nothing improper about modifying the system message catalog
-- many users do it, and HP even tells you how to do it in Chapter 9 of the
System Operation and Resource Management Manual (pp.  9-55/57 of the June 1987
edition).  The TERMUNLK job stream uses this documented, non-privileged method,
and is perfectly safe.

Finally, there are a few other keywords you might use if you find that LOGOFF
doesn't quite work right when aborting a session.  (As you may have noticed
from what we say in this chapter, all computer systems seem subtly different --
the default LOGOFF method, which works for 90% of our users, sometimes needs
some modification for the remaining 10%.)


ABORTIO, LOGOFF configuration keyword ``NOABORTIO
$ABORTIO, LOGOFF configuration keyword
$NOABORTIO, LOGOFF configuration keyword

   $ABORTIO

         If you specify the $ABORTIO keyword, LOGOFF will do an :ABORTIO before
         doing the :ABORTJOB.  Our experience has been that this is not
         necessary, but we allow you to do this for compatibility with previous
         versions.  Default is $NOABORTIO.


NOPREEMPT, LOGOFF configuration keyword ``preempt
$NOPREEMPT, LOGOFF configuration keyword
$SOFTPREEMPT, LOGOFF configuration keyword
$HARDPREEMPT, LOGOFF configuration keyword

   $NOPREEMPT
   $SOFTPREEMPT
   $HARDPREEMPT

         By default, LOGOFF outputs the message to the terminal with "hard
         preemption", i.e.  aborting any read that might be in effect on the
         terminal (just like the :WARN command does).  You may, if you wish,
         choose "soft preemption" (i.e.  only aborting the read if no
         characters have actually been typed yet by the user) or "no
         preemption", although our experience has been that $HARDPREEMPT (the
         default) is better.

Finally, note that we let you entirely redefine what we do when we abort user
sessions -- if you want to, you can look at the Further Controlling Aborts
chapter below.  As a general rule, though, either the default LOGOFF settings
or the default settings plus a few of the above keywords should be enough to do
the job.


Configuring LOGOFF: sending warnings ``contents
Configuring LOGOFF: sending warnings


WARNTIME, LOGOFF configuration keyword ``warning`timeout
$WARNTIME, LOGOFF configuration keyword
$WARNMESSAGE, LOGOFF configuration keyword
of the major reasons to use LOGOFF is to prevent people from leaving their
terminals unattended (and thus usable by anybody) for a long time.  What if
that's all you want to do -- what if you don't want to abort people whose
terminals are merely idle as long as the people themselves are near the
terminals and able to monitor who's using them?

Obviously, it's impossible for the computer to determine whether a user has
really left his terminal or is near it but just not using it.  (Hmmm -- maybe
we could set up some infra-red sensors or a video camera with a digitizer...
No, probably not.)

However, LOGOFF does let you warn users a few minutes before they're actually
aborted, so that before the abort actually happens they can do something to
prevent it.  All they'd really have to do is to hit [RETURN] (or [ENTER], if
they're in block mode) once so that the session uses a little bit of CPU time;
once that happens, LOGOFF will see that there's been some activity on their
terminal and not abort it (since it's not idle).

Configuring this warning feature is simple -- you should simply add a $WARNTIME
keyword and a $WARNMESSAGE keyword to the LOGOFF.DATA.VESOFT file:

   $WARNTIME 300
   $WARNMESSAGE "You'll be aborted shortly if your terminal is idle!"

The $WARNTIME specifies (in seconds) how long before the actual abort the user
will be warned; the $WARNMESSAGE indicates the warning message that will be
sent to the user.  When LOGOFF realizes that the user has been idle for
($TIMEOUT - $WARNTIME) seconds -- e.g.  if $TIMEOUT is 1800 (30 minutes) and
$WARNTIME is 300 (5 minutes), this would be after at least 25 minutes of
idleness -- LOGOFF will send him the $WARNMESSAGE.

Now, one of our concerns is that the $WARNMESSAGE be as non-intrusive as
possible (while still being noticeable).  Say that the user is in the middle of
a block mode screen; we wouldn't want to write over any of the data he's typed.
How can we deliver the message to him and still not injure the data on the
screen?

Fortunately, most HP terminals -- from the HP 262x on up, certainly including
the 2392 and the 700 series -- let you put a message on the 25th line of the
screen, temporarily overwriting the function key labels.  The message will go
away the next time the user hits the [RETURN] key, and the function key labels
are brought back; none of the other data on the screen goes away.

The only things that the user will thus have to do to recover from this message
is to hit the [return] key an extra time (to reset his function keys) and move
the cursor up one line to the place at which it was before the message arrived.
Unfortunately, the transmission of the message moves the cursor down one line,
so the user will have to compensate for that.

One other thing to keep in mind: remember that LOGOFF is asleep most of the
time, only waking up every $PAUSETIME seconds (see below) to look around and
see who is supposed to be aborted or warned.  We make sure that we wake up
often enough to be certain that we get a chance to warn a user before aborting
him; however, it's quite possible that the "5-minute warning" will arrive only
one or two minutes before the user is actually aborted.

If you want to be more precise about the warning time -- make sure that a user
has, say, between 4 and 5 minutes to respond to the warning, you should make
the $PAUSETIME smaller; for instance, if you say "$PAUSETIME 60" to make LOGOFF
wake up every minute, LOGOFF can be precise to within a minute.

The problem with a small $PAUSETIME is, of course, that every time LOGOFF wakes
up it has to use some CPU time to perform its observations; the lower the
$PAUSETIME, the more system resources it will use.

Thus, as we discuss in more detail in the $PAUSETIME section below, you have to
strike a balance between precision and performance.  Our opinion is that it's
usually enough to have the warning appear some time before the abort (we
automatically set the $PAUSETIME to be at most $WARNTIME - 30, so that
everybody will have at least 30 seconds to respond to the warning) -- if the
user is really at the terminal, he should have no trouble hitting return or
[ENTER] once to avoid getting aborted.


WARNTIME, LOGOFF keyword; affect upon $PAUSETIME keyword
$WARNTIME, LOGOFF keyword; affect upon $PAUSETIME keyword
also that since we set $PAUSETIME to be $WARNTIME - 30, a low $WARNTIME
will lower the $PAUSETIME and thus cause LOGOFF to use more CPU resources.  You
should keep this in mind when setting these values.

Configuring LOGOFF: "LOCKING UP" sessions that use menus

Sometimes, you don't want to abort a session just because it's been idle; what
you really want to do is to prevent people from walking up to an idle terminal
and usurping the session logged on to it.

Unfortunately, for normal MPE sessions, the only way to do this is to abort the
session -- MPE doesn't let us somehow "lock up" another terminal to prevent
people from accessing it until they, say, re-enter their password.  If,
however, you're using SECURITY logon menus, we have a little bit more control.

If you say, in your SECURCON.DATA.VESOFT file (the main configuration file used
by the SECURITY logon module),


MENU-LOGOFF-LOCKUP, SECURCON file keyword ``LOGOFF`LOCKUP
$MENU-LOGOFF-LOCKUP, SECURCON file keyword

  $MENU-LOGOFF-LOCKUP @.@

then, when LOGOFF finds the terminal idle, LOGOFF will not abort it.  Instead,
it will tell the SECURITY menu handler running on that terminal to:

   * abort whatever selection the user was then running;

   * prompt the user for his MPE, SECURITY, and/or terminal passwords (just
     like the LOCKUP entry point of MAIN.PUB.VESOFT [documented above] would
     do);

   * log him off the system if he does not correctly enter the passwords;

   * bring him back to the menu's "Enter selection:" prompt if he does
     correctly enter the passwords.

Thus, you'll be protected against some unauthorized person who has access to
the terminal (since he'd have to enter the password in order to use it);
however, you won't go through the overhead of an extra log off and log on.

By default, the user will be sent the message "LOGOFF: ** PASSWORDS RE-PROMPTED
FOR DUE TO LACK OF ACTIVITY **" before being re-prompted for his passwords; you
can change this message by saying (in the LOGOFF.DATA.VESOFT file):


MENULOCKUPMESSAGE, LOGOFF configuration keyword ``lockup`message
$MENULOCKUPMESSAGE, LOGOFF configuration keyword

  $MENULOCKUPMESSAGE "yourmessage"

A few technical implementation notes:

   * If LOGOFF decides to "lock up" the session when the user is at the "Enter
     selection:" prompt, the user will not be re-prompted for his passwords
     until after he enters a selection.  Then, he will be re-prompted for his
     passwords, and the chosen selection will be executed.

   * When LOGOFF tells the menu processor to abort the selection being run, the
     menu processor will do this by killing whatever son process it might be
     running and then setting the JCW to FATAL.  This will cause the remainder
     of the selection to be flushed unless there's a CONTINUE command in the
     menu file before the RUN of the program.

     This can actually be a good feature because it can make sure that
     appropriate cleanup work is done when a menu option is aborted.  For
     instance, if you know that some temporary files must be purged after the
     program finishes (normally or because of a LOGOFF abort), your menu might
     say:

        *CAPTION VENDOR MAINTENANCE
        CONTINUE
        RUN VNDMAINT.PUB.AP
        PURGE TEMPVND,TEMP
        PURGE TEMPVND2,TEMP


SECURITYMENULOGOFFLOCKUP, LOGOFF JCW ``menu`lockup
SECURITYMENULOGOFFLOCKUP, LOGOFF JCW

    You can even specifically check to see if a program was terminated due to
     a LOGOFF abort by checking the SECURITYMENULOGOFFLOCKUP JCW -- if it's
     equal to 1, this means that this program was aborted by LOGOFF.

   * If you run MAIN.PUB.VESOFT with the MENU entry point, LOGOFF will try to
     "lock up" your session just as it would for the LOGON entry point.  What
     this means is that you must check the SECURITYANSWER JCW after you run
     MAIN.PUB.VESOFT with the MENU entry point and do a BYE command if
     SECURITYANSWER=1 (which indicates that the user entered the password
     incorrectly).

     Thus, a typical UDC that runs MAIN.PUB.VESOFT,MENU would look like:

        SECMENU !FILENAME
        OPTION NOBREAK
        SETJCW SECURITYANSWER = 0
        FILE MENUFILE = !FILENAME
        CONTINUE
        RUN MAIN.PUB.VESOFT,MENU
        IF SECURITYANSWER = 1 THEN
          BYE
        ENDIF

     (You can find this UDC in our LOGONUDC.PUB.VESOFT UDC file.) Note that
     this is somewhat different from earlier versions of SECURITY -- before,
     there was no reason for you to check SECURITYANSWER after using the MENU
     entry point, but now there is (if you use $MENU-LOGOFF-LOCKUP).


Configuring LOGOFF: multiple $TIMEOUTs ``contents
Configuring LOGOFF: multiple $TIMEOUTs

Say that you build your LOGOFF.DATA.VESOFT file to contain:

   $MESSAGE "** ABORTED DUE TO LACK OF ACTIVITY **"
   $TIMEOUT 600
      $USERS INCLUDE @.PAYROLL
      $PROGRAMS INCLUDE @.PUB.PAYROLL QUERY.PUB.SYS

Then, when LOGOFF is run, it'll abort any PAYROLL account sessions that are
running any PUB.PAYROLL program or QUERY.PUB.SYS and have been idle more than
10 minutes (600 seconds).

What if you want LOGOFF to also abort some other users, but with a different
timeout? Or, perhaps, use the same timeout but specify different $USERS,
$PROGRAMS or $TERMINALS restrictions? Or issue a different $MESSAGE?

The LOGOFF.DATA.VESOFT file may contain not just one set of $ keywords, but up
to 10 different sets.  For example, it might say:

   $TIMEOUT 600
      $USERS INCLUDE @.AP
      $TERMINALS EXCLUDE 21 22 23
   $TIMEOUT 1200
      $USERS INCLUDE @.PAYROLL
      $TERMINALS EXCLUDE 22

This means that

   * Any users in the AP account (except those on terminals 21, 22, or 23) will
     be aborted after 10 minutes (600 seconds) of idleness;

   * Any users in the PAYROLL account (except those on terminal 22) will be
     aborted after 20 minutes (1200 seconds) of idleness.

The "delimiters" between the different keyword sets are the $TIMEOUT commands.
Everything after the first $TIMEOUT but before the second is one keyword set,
controlled by the first $TIMEOUT; everything after the second $TIMEOUT (but
before the third) is another keyword set, controlled by the second $TIMEOUT.
In general, the LOGOFF.DATA.VESOFT file may look like:

   global keywords equally applicable to all keyword sets
   $TIMEOUT timeout1
      keyword set 1, governed by timeout1
   $TIMEOUT timeout2
      keyword set 2, governed by timeout2
   ...
   $TIMEOUT timeoutN
      keyword set N, governed by timeoutN

For example,

   $MESSAGE "*** IN THE FUTURE, PLEASE LOG OFF WHEN INACTIVE! ***"
   $CPUTHRESHOLD 0.5
   $TIMEOUT 600
      $USERS INCLUDE @.AP
   $TIMEOUT 900
      $USERS INCLUDE @.PAYROLL @.DEV
      $PROGRAMS EXCLUDE EDITOR.PUB.SYS
   $TIMEOUT 300
      $SELECT "BETWEEN (CLOCK, 6PM, 6:30PM)"
      $USERS EXCLUDE JACK,@.@

defines three different keyword sets:

   * According to keyword set 1, any session in the AP account will be aborted
     after 10 minutes of idleness;

   * According to keyword set 2, any session in the PAYROLL or DEV account
     (except those running EDITOR.PUB.SYS) will be aborted after 15 minutes of
     idleness;

   * According to keyword set 3, between 6 PM and 6:30 PM, any session (except
     those logged on with session name JACK) will be aborted after 5 minutes of
     idleness.

The $MESSAGE and $CPUTHRESHOLD keywords, being before the first $TIMEOUT
keyword, apply equally to all three keyword sets.

Note that the keywords following each $TIMEOUT are indented for readability (so
that you could see how each keyword set is defined).  The leading spaces are
ignored by LOGOFF; in general, LOGOFF considers all multiple spaces to be one
space (except in quoted strings).  It's the $TIMEOUT keywords -- not the line
indentations -- that separate the keyword sets from one another.


Configuring LOGOFF: $PAUSETIME ``contents
Configuring LOGOFF: $PAUSETIME

As we mentioned earlier, LOGOFF spends most of its time sleeping; every so
often, it wakes up, checks the state of the system, aborts any sessions that
should be aborted, and goes back to sleep.

This is, of course, done for efficiency -- you don't want LOGOFF to be
constantly running, constantly checking the state of the system; it would just
take too much CPU time.  By default, LOGOFF wakes up every 5 minutes (unless
one of the $TIMEOUTs is less than 5 minutes, in which case it wakes up as often
as the shortest $TIMEOUT value).

There are two reasons you might want to change this value:

   * Although LOGOFF has been heavily optimized to use the minimum amount of
     CPU resources, on a large and heavily loaded system, you may want it to
     wake up less frequently.

   * On the other hand, if your $TIMEOUT value is 15 minutes and LOGOFF wakes
     up every 5 minutes, then a session could remain idle for as long as almost
     20 minutes without LOGOFF aborting it; on the average, aborts would happen
     after 17.5 minutes of idleness, since LOGOFF may be asleep when the exact
     15 minutes of idleness are up.  Therefore, you may want to shorten the
     LOGOFF pause time, especially if you're using short $TIMEOUTs (e.g.  5 or
     10 minutes).

Changing the pause time is very simple -- just add a line of the format

   $PAUSETIME numseconds
   e.g.  $PAUSETIME 150

to your LOGOFF.DATA.VESOFT file.  "$PAUSETIME 120" sets the pause time to 2
minutes; "$PAUSETIME 600" would set the pause time to 10 minutes.

Note that unlike all other keywords (which may be repeated once in each keyword
set, i.e.  once for each $TIMEOUT entry), $PAUSETIME should appear in your
LOGOFF.DATA.VESOFT only once.


Showing system status ``contents
Showing system status

There are two LOGOFF entry points that let you see the current status of the
system.  They are run ONLINE (rather than in batch), and can be rather useful
system manager control tools.


STATUS, MAIN.PUB.VESOFT entry point
you say

   :RUN MAIN.PUB.VESOFT,STATUS

LOGOFF will show you information on all the currently running sessions, as well
as what LOGOFF "thinks about them".  The format of this display looks like:

   LDEV  SESS         CPU  IDLE  STATUSES    LOGON
         #           SECS  SECS  0123456789  ID
   ----  ----        ----  ----  ----------  -----
   20   #S8      2164.930   155  UT.         EUGENE,MANAGER.VESOFT,DEV
   22   #S9      1460.418   920  PT!         JACK,CLERK.PAYROLL,PUB
   ...

As you see, the terminal number (LDEV), the session number, total number of CPU
seconds spent by this session, the number of seconds that the session has been
idle, and the session's logon id are all printed.  (The currently active
program, if any, is also printed.)


STATUSES, LOGOFF display field
are those cryptic characters displayed in the "STATUSES" field? They
indicate LOGOFF's "opinion" of this session.  Column 0 indicates whether or not
this session is covered by keyword set 0 (the one belonging to the first
$TIMEOUT), column 1 indicates whether or not it's covered by keyword set 1, and
so on.  Each column can have one of the following values:

   S     This session doesn't match the keyword set's $SELECT
   T     This session is not on any of this keyword set's included $TERMINALS
   U     This session doesn't belong to any of this keyword set's included
          $USERS
   P     This session isn't running any of this keyword set's included
          $PROGRAMS
   d     This is a DS session and $NODSABORT is set
   l     This is a LAN session and $NOLANABORT is set
   n     This is a new session (which didn't exist the last time LOGOFF woke
          up)
   *     This session is active (i.e.  has used more than $CPUTHRESHOLD CPU
          time since LOGOFF last woke up)
   ~     This session has no terminal I/O pending
   .     This session is idle, but hasn't been idle long enough to be aborted
   :     This session is ripe for being warned
   !     This session is ripe for aborting

This status information can be quite helpful if you're wondering why a
particular session is or is not being aborted -- they can remind you of
particular LOGOFF configuration options that may be governing the session but
of which you are unaware.

In order for the STATUS entry point to work, the background LOGOFF task must be
running -- this LOGOFF task is where the STATUS entry gets idle time
information from.  If LOGOFF is not currently running, the STATUS entry point
will not print anything; you could, however, say


SNAPSHOT, MAIN.PUB.VESOFT entry point

   :RUN MAIN.PUB.VESOFT,SNAPSHOT

This will print you the same information as STATUS except that the idle time
will always be shown as 0.

Note that the "idle seconds" field displayed by the STATUS entry point actually
means "the number of seconds since LOGOFF detected activity on the part of this
session".  If a session is completely excluded (from all keyword sets) by a
$SELECT, $TERMINALS, $USERS or $PROGRAMS, LOGOFF won't even bother to look for
any session activity (so as not to waste time); therefore, the "idle seconds"
field is not valid for any session that's completely excluded from all keyword
sets by a $SELECT, $TERMINALS, $USERS or $PROGRAMS (or $NODSABORT or
$NOLANABORT).

Also note that if you use $CPUTHRESHOLD, you'll sometimes see a number in the
"CPU SECS" column and, below it, another number in parentheses.  For example,
the display might look like:

LDEV  SESS         CPU  IDLE  STATUSES    LOGON
      #           SECS  SECS  0123456789  ID
----  ----        ----  ----  ----------  -----
20   #S8      2164.930   155  UT.         EUGENE,MANAGER.VESOFT,DEV
                (0.095)

The number in parentheses (here 0.095) is the number of CPU seconds that this
session has used in its most recent "idle period" (here the last 155 seconds).
The above line shows that #S8 has actually accumulated 2165.025 (2164.930 plus
0.095) seconds of CPU time, but the 0.095 that it has accumulated in the past
155 seconds will be ignored because they are less than the $CPUTHRESHOLD value.

Viewing the $STDLIST output of LOGOFF


SLOGOFF.DATA.VESOFT, STDLIST output of BACKG task LOGOFF``news
SLOGOFF.DATA.VESOFT, STDLIST output of BACKG task LOGOFF


LOGOFF, BACKG TASK; see also %BACKG in the MPEX manual
is a "BACKG task", which means that it is executed as part of the BACKG
job.  (see the MPEX manual under %BACKG for complete details) Although LOGOFF
still generates $STDLIST output, the output is directed to a disk file called
SLOGOFF.DATA.VESOFT instead of the job's actual $STDLIST file.  This is a
normal MPE file with shared access, so you can view this file at any time (even
when the job is running) using a %PRINT command.


BACKG shows logoff PENDING instead of EXECUTING
output of SLOGOFF.DATA consists of the contents of the LOGOFF.DATA file
followed by a log-listing of each attempt LOGOFF makes to abort "idle"
sessions.  If you suspect that LOGOFF is not working, issue a "%BACKG SHOW"
command to see if logoff is EXECUTING.  If you see that logoff is PENDING
instead of EXECUTING, (and the job is running), review the file
SLOGOFF.DATA.VESOFT for error messages that may explain WHY logoff isn't
running.  (The most common cause of this condition is an error in the
LOGOFF.DATA configuration file.  Since this is printed first, any errors will
show up immediately after starting LOGOFF.)


Further controlling what happens at abort time ``contents
Further controlling what happens at abort time
LOGOFFAB.PUB.VESOFT, LOGOFF abort configuration file

NOTE: This section describes a powerful yet somewhat difficult to use feature
      of LOGOFF.  You should not normally have to use it; beginning users can
      easily skip this section.

Sometimes, you want to very tightly control what exactly happens when LOGOFF
aborts a session.  For instance, LOGOFF normally does :ABORTIO of the terminal
before doing an :ABORTJOB; some of our customers find it necessary to do an
:ABORTIO AFTER the :ABORTJOB as well (because of some peculiarity of their
terminal controllers).  Other customers may want to disable the special
messages that LOGOFF normally sends to the console whenever a job is aborted.

There have actually been relatively few requests such as this, since the
standard LOGOFF mechanism, especially when fine-tuned as we discussed above,
works quite well for 99% of our users.  Therefore, instead of adding special
LOGOFF.DATA.VESOFT $ keywords for each such request, we let you completely
redefine what LOGOFF does at session abort time.

The file LOGOFFAB.PUB.VESOFT is a little "expression program" (see Appendix of
this manual).  Syntactically, it looks very much like a PASCAL program; in
fact, we have our own little internal PASCAL compiler that parses it.  Here's
what LOGOFFAB.PUB.VESOFT might look like:

   IF LDEV<>HPCONSOLE THEN
     BEGIN
     MPE (STRWRITE ("ABORTIO ", LDEV));
     WRITELN (HPDATEF, ", ", HPTIMEF, " - ABORTING #S", JSNUMBER, ", ",
              FMTLOGON, " (LDEV ", LDEV, ")");
     TERMWRITE (0,
                CHR(27)+"X"+     (* turn off FORMAT mode *)
                CHR(27)+"F"+     (* HOME DOWN *)
                CHR(27)+"&k0B"+  (* turn off BLOCK mode *)
                CHR(27)+"&jR"+   (* unlock function keys *)
                CHR(27)+"g"+     (* do a soft reset -- *)
                                 (*   you may want to delete this *)
                20*CHR(6)+       (* wait a while after the reset *)
                LOGOFFMESSAGE);
     MPE ("TELLOP LOGOFF: #S"+STRWRITE(JSNUMBER)+", "+FMTLOGON);
     MPE ("TELLOP .       ABORTED DUE TO LACK OF ACTIVITY!");
     PAUSE (1);
     MPE ("ABORTJOB #S"+STRWRITE(JSNUMBER));
     END;

What does all this mean?


Allowing LOGOFF to abort the console

  * All the text is wrapped in a

        IF LDEV<>HPCONSOLE THEN
          BEGIN
          ...
          END;

     This makes sure that the system console is never aborted.  (Some of our
     users may want to allow the console to be aborted; they can just delete
     the IF, the BEGIN, and the END.) Note that LDEV is defined by LOGOFF to be
     the Logical DEVice number currently being aborted; HPCONSOLE is defined by
     our general Expression Processor (see Appendix) to be the logical device
     number of the system console.

   * The first statement after the BEGIN is

        MPE (STRWRITE ("ABORTIO ", LDEV));

     To fully understand this, you should look up the MPE and STRWRITE
     functions in Appendix to this manual -- what this really does is execute
     an "ABORTIO ldev" MPE command.

   * Next comes

        WRITELN (HPDATEF, ", ", HPTIMEF, " - ABORTING #S",
                 JSNUMBER, ", ", FMTLOGON, " (LDEV ", LDEV, ")");

     The WRITELN statement outputs a line to the job's $STDLIST -- that way,
     when LOGOFF is stopped, you can see whom it aborted (Note: the STDLIST for
     LOGOFF is re-directed to the file SLOGOFF.DATA.VESOFT).  JSNUMBER is
     defined by LOGOFF to mean the session number of the session being aborted;
     FMTLOGON is its logon ID ("jobname,user.account,group").


TERMWRITE, function used in the LOGOFFAB file

  * After this comes

        TERMWRITE (0, ...  LOGOFFMESSAGE);

     TERMWRITE is a special function defined for use in the LOGOFFAB.PUB.VESOFT
     file; it takes as parameters an integer (here 0) and a string.  It outputs
     the string (here several escape sequences followed by LOGOFFMESSAGE, the
     variable that contains the defined $MESSAGE text) to the terminal being
     aborted.  The integer is the preemption level -- 0 means a normal output,
     1 is equivalent to $SOFTPREEMPT, and 2 is equivalent to $HARDPREEMPT.

   * Now come

        MPE ("TELLOP LOGOFF: #S"+STRWRITE(JSNUMBER)+", "+FMTLOGON);
        MPE ("TELLOP .       ABORTED DUE TO LACK OF ACTIVITY!");
        PAUSE (1);

     The MPE, STRWRITE and PAUSE functions are all documented in the Appendix
     -- these three lines just send some messages to the system console and
     then pause for a second.  The pause for a second is there to let the
     message that TERMWRITE output come out on the terminal before the
     :ABORTJOB actually begins.

   * Finally, the real work:

        MPE ("ABORTJOB #S"+STRWRITE(JSNUMBER));

     This executes the :ABORTJOB command that actually aborts the session
     involved.

As you can see, this is all a fairly complicated process (though the
fundamental rules for it are the same ones as for STREAMX expressions, MPEX
selection conditions, MPEX flexible LISTF files, SECURITY LISTLOG/LISTUSER
selection conditions, etc.  that are described in Appendix); however, if you
really need to tinker with it, you can.  For example:

   * By removing the IF, BEGIN and the END, you can permit the console to be
     aborted.

   * By adding another MPE (STRWRITE("ABORTIO ", LDEV)) after the ABORTJOB, you
     can tell LOGOFF to do that extra ABORTIO.

   * By removing or altering the MPE ("TELLOP "...) commands you can change
     what message end up on the console.

   * By adding an extra TERMWRITE, you can output a multi-line message to the
     terminal being aborted.

   * By adding

      SECURITYLOG ("LOGOFF: Aborting #S"+STRWRITE(JSNUMBER)+", "+
                   FMTLOGON+" (LDEV "+STRWRITE(LDEV)+")");

     you can have LOGOFF write a log record to the SECURITY log file whenever
     it aborts someone (see "SECURITY's Logging Facility" in the Logon Security
     section of this manual).

We recommend that you do not modify LOGOFFAB.PUB.VESOFT directly, since any
changes you make will be wiped out the next time you install the new version of
LOGOFF.  Instead, copy LOGOFFAB.PUB.VESOFT into some other file, make some
changes, and then say

   FILE LOGOFFAB.PUB.VESOFT=yourownfilename

in your BACKGINI.DATA.VESOFT file.

In general, the LOGOFFAB.PUB.VESOFT file can contain any of the predefined
functions and variables described in Appendix, plus:

   LDEV             [INT]  The LDEV being aborted.
   JSNUMBER         [INT]  The session number being aborted.
   FMTLOGON         [STR]  The logon ID of session being aborted
                                (e.g.  "JACK,CLERK.PAYROLL,PUB").
   JSNAME           [STR]  The session's session name.
   USER             [STR]  The session's user ID.
   ACCOUNT          [STR]  The session's account name.
   GROUP            [STR]  The session's group name.
   LOGOFFMESSAGE    [STR]  $MESSAGE from LOGOFF.DATA.VESOFT.
   LOGOFFNOABORTIO  [BOOL] TRUE if $NOABORTIO was specified in
                             LOGOFF.DATA.VESOFT, FALSE by default.
   LOGOFFNOBLOCK    [BOOL] TRUE if $NOBLOCK was specified in
                             LOGOFF.DATA.VESOFT, FALSE by default.
   LOGOFFPREEMPT    [INT]  1 if $SOFTPREEMPT was specified in
                             LOGOFF.DATA.VESOFT,
                             2 if $HARDPREEMPT, 0 by default.

These variables can be used just as you would use the standard predefined
variables -- HPACCOUNT, HPJOBCOUNT, etc.  -- except that they're only usable in
the LOGOFFAB.PUB.VESOFT file (or whatever file you have it :FILE equated to).

The "real" LOGOFFAB.PUB file that we provide differs from the example we first
showed in that we check LOGOFFNOABORTIO and LOGOFFNOBLOCK (and also use
LOGOFFPREEMPT in the TERMWRITE call).  This is largely for compatibility -- if
we were initially writing LOGOFF today, we wouldn't implement $NOABORTIO,
$NOBLOCK, $SOFTPREEMPT and $HARDPREEMPT at all, but rather have you modify
LOGOFFAB.PUB.VESOFT if you needed to.


LOGOFFWR.PUB.VESOFT, LOGOFF warning configuration file
use a very similar file (called LOGOFFWR.PUB.VESOFT) for controlling what
happens at pre-abort warning time -- if you understand how LOGOFFAB.PUB.VESOFT
works, you should have no trouble reading the LOGOFFWR file and making whatever
modifications you feel are appropriate.


TERMWRITENOCRLF, function used in the LOGOFFWR file
feature that we use in the standard LOGOFFWR file but do not use in the
standard LOGOFFAB file is the TERMWRITENOCRLF function -- it's just like a
TERMWRITE but it sends its message without a carriage return and line feed at
the end.  You can use TERMWRITENOCRLF and TERMWRITE in either file; it just so
happens that TERMWRITE is more useful in the abort sequence and TERMWRITENOCRLF
is more useful in the warning sequence.

Introduction: Database security

We secure things to prevent unauthorized access.  "They" -- the bad guys -- are
out to get Our stuff, and we want to stop them.  The more precious the
possession, the more They want to get at it, and the more We want to protect
it.  Why is it, then, that IMAGE databases -- the repositories of the
overwhelming majority of important and sensitive data that people keep on
HP3000s -- are the least secured things on the entire computer?

Now, first let me prove that we're not just crying "Wolf!" You should never ask
a barber whether or not you need a haircut, and as a vendor of security
software, we're inherently suspect when we speak of a need for additional
security.  Still, we believe a problem exists, and we'll explain why.

No one can say that IMAGE wasn't designed with security in mind.  There's a
pretty intricate security mechanism built into IMAGE: a database administrator
can not only restrict access to the database, but also to each individual
dataset and even a data item within a dataset; he can prevent both read and
write access or allow only read access; he can establish up to 63 classes of
users, each of which have different capabilities.

What, then, is the problem? Well, we claim that

   * IMAGE database passwords can not truly protect your IMAGE database.

Consider: You establish some access class that allows someone to read and write
the VENDORS dataset of your accounts payable database.  You aren't really doing
it for the benefit of a specific USER; rather, there's a Vendor Maintenance
program that has to be able to read and update the dataset.  You might trust
the program itself to make sure that the user is authorized to use the program,
but the program itself must be "authorized" to access the database in the
specified user class.  The only way this can really be done is by "telling" the
program the database password, and therein lies the rub:

   * Even if you set up the most sophisticated security restrictions within
     your IMAGE database, all programs that want to access it must physically
     contain the database password.

Somewhere in your program there must be embedded the database password.  The
program's author had to know it; the program's maintainer knows it; anybody who
has access to the program's source code (do you keep your source code tightly
secured?) knows it; anybody who has read access to the program file can deduce
the password with :FCOPY ;CHAR.

The trouble with IMAGE passwords is the same as the trouble with any embedded
passwords:

   * By reading a program that accesses your database, anybody can find out the
     database password;

   * Since your database password is embedded in your programs, it's very hard
     to change since it requires source code changes and re-compilation.

If someone wanted to break into your database, all he'd have to do is find some
unsecured source file and look at the DBOPEN call; then, he can use QUERY, or,
even if you have QUERY access to your database disabled, he can write a short
program of his own that DBOPENs your database and reads (or writes!) whatever
it wants to.

What we're really seeing here is a sophisticated IMAGE security system that's
based on the entirely wrong thing.  Instead of forbidding or allowing access by
user ID (only JOE.AP can access the vendor dataset) or by program (only the
program VENMAINT.PUB.AP can access the vendor dataset), access is dictated by
whether or not the caller knows the IMAGE password -- a password that, as we
see, is not really secured in any sense of the word.

   * What's really needed is an IMAGE security system driven by who you are and
     what program you're running, not whether or not you know the IMAGE
     password.

This is something that IMAGE doesn't provide, and this is exactly what we're
advocating as the correct way of securing your IMAGE database.

The principle of VESOFT's database security system is that each database has
its own "access control file".  This file dictates who -- which program and
which user -- can access the database in which modes and which user classes.

For instance, you can set up access class #10 (or whatever other number you
choose) which allows reading and writing the vendor dataset, and then say that
only the users JOE.AP and CATHY.AP can access it, and then only when running
the program VENMAINT.PUB.AP (which might impose some of its own restrictions).

Or, you can have just one access class that allows access to the entire
database (many people do this just for simplicity's sake), and then describe in
great detail which users running which programs can do what to the database.

It might even be enough for you to allow anybody running a particular program
to access the database, since then that program can impose its own security
system, being certain that the only way anybody can access the database is by
running that program.

Once you've set up the access control file, the question becomes: how do you
enforce the restrictions you've specified in it? Well, we could have replaced
your DBOPEN intrinsic by our own, one that pays attention to the access control
file, but we really don't want to change IMAGE at all.

Instead, we've written our own procedure called VEOPEN, which enforces the
access control file restrictions; all you need to do is change your programs
that call DBOPEN to call VEOPEN (we even have a mechanism for changing program
files directly -- without recompiling -- in case you don't have the source
code).

Finally, once you've switched to VEOPEN, the database administrator change all
of the database's passwords.  These new passwords will remain secure because
nobody (except, perhaps, the DBA) will need to know them to access the database
-- the DBA can change them again whenever he wants to, without changing any
program.  We even have an option by which he can automatically set all the
passwords to random character sequences that nobody will have to know about.

So, the principle of VESOFT's IMAGE Security is this:

   * Set up an Access Control File which allows you to restrict access

       - by user id (session, user, account, and/or group);

       - by program file;

       - by access mode (e.g.  5 through 8 for read-only access);

       - and, if you want to, by a user-supplied password.

   * Change your programs to call "VEOPEN" instead of "DBOPEN"; you can change
     the source code of programs whose source code you have or directly change
     the program files when you don't have source code.  You can change QUERY,
     QUIZ, QUICK, etc.  the same way!

   * Finally, to prevent anybody from accessing the database without calling
     "VEOPEN", you can either have us automatically set up random database
     passwords or set up passwords of your own that nobody but the DBA will
     know and that you can change any time you want to.

   * Our system works hand-in-hand with IMAGE's internal security, so you can
     still restrict access by dataset, by data item, and by read/write access.


Setting up the VEOPEN access control file (ACF) ``contents
Setting up the VEOPEN access control file (ACF)

As we mentioned before, you can restrict database access by several criteria:

   * By user ID, which means any combination of session name, user ID, account
     name and/or group name.  Wildcards are OK, so you can allow access to,
     say, "JOE,@.@" or "CLK@.AP".

   * By program name.  You can, for instance, allow access to the database only
     through a certain program, which can do its own special security checking.
     Wildcards, incidentally, are also allowed.

   * By IMAGE DBOPEN mode.  Different restrictions may be placed on people who
     want to modify data rather than just read; in fact, you can give special
     restrictions for any mode from 1 to 8.

   * By password.  For compatibility with some existing IMAGE programs that may
     open the database with one of several passwords, and for greater
     flexibility for users who want it, you can also control access by the
     password provided to VEOPEN.  We think, however, that you'll find the
     user, program, and mode restrictions sufficient most of the time, in which
     case the password passed to VEOPEN will be ignored.

   * By any combination of the above.  You can, for instance, restrict access
     to JOE.AP and CATHY.AP who are running a program in the fileset AP@.PUB.AP
     and are trying to access the database in modes 5, 6, 7 or 8.

For each such combination of restrictions, you can specify what user class
should be granted to the user who satisfies these restrictions.  These
specifications should be put into an ACCESS CONTROL FILE, whose name must be
the same as the name of the database followed by the letters "VE" (e.g.  the
database "APBASE.DATA.AP" would have an access control file called
"APBASEVE.DATA.AP").  Such a file might look like:

   $USER BOSS.AP                                $CLASS 10
   $USER @.AP  $PROGRAM AP@.PUB.AP              $CLASS 7
   $USER CLERK.AP AUDIT.AP  $MODE 5 6 7 8       $CLASS 5
   $PROGRAM QUERY.PUB.SYS  $MODE 5              $CLASS 4
   $USER @.AP                                   $CLASS 3

What does this mean?

   - The MPE user BOSS.AP, running any program, will be granted access to the
     database in user class 10 (what this user class will actually be allowed
     to access is specified, as usual, in the schema definition).  Presumably,
     you've secured BOSS.AP using MPE and/or SECURITY, so you can be sure that
     it's OK to let him access the database.

   - Any user in the AP account who's running the programs AP@.PUB.AP will be
     granted access in user class 7.  APMAIN.PUB.AP, for example, can then
     impose its own security restrictions by calling the WHO intrinsic and
     giving various users various access rights depending on who they are --
     for instance, it might allow only certain users to write checks, modify
     invoice information, etc.

   - Any user who logs on as AUDIT.AP or CLERK.AP and requests access in DBOPEN
     modes 5, 6, 7 or 8 (the read-only modes) will be granted access in user
     class 5.

   - Anybody running QUERY and trying to open the database in mode 5 will be
     granted access in user class 4.

   - Any other user in the AP account, running any program with any database
     mode, will be granted access in user class 3.

   - Anybody else who doesn't meet one of these restrictions will be forbidden
     to access the database entirely.

First, notice the power and ease of use here.  You can combine any of the
restrictions with any others; you can specify several user names, filenames or
modes in one line; you can specify users and filenames using wildcards.  Also,
note some key features:

   - The access control file indicates what user class each user will be
     granted access in.  Presumably, the database schema defines just which
     datasets and data items user classes 10, 7, 3, 2 and 1 can access.  VEOPEN
     just dictates which user class a particular would-be database accessor
     will be associated with.  Of course, this works with a system of any
     complexity; even if you have only one user class, which can access
     anything in the database, you can still restrict to that one class by any
     combination of user, program, mode, and password.

   - When there are several sets of restrictions, ambiguities will naturally
     result.  If BOSS.AP runs QUERY.PUB.SYS in mode 5, should he get class 10
     or class 4? VEOPEN's rule is that the first restriction that's satisfied
     is the one that's used, so since the "$USER BOSS.AP $CLASS 10" comes
     earlier in the file than "$PROGRAM QUERY.PUB.SYS $MODE 5 $CLASS 4", the
     user will get class 10.  This is a very useful feature, since it allows
     you to control access rights very exactly and very conveniently, just by
     putting the more specific ones first and the more general ones last.

   - The format of the file is very free.  You can put several restrictions on
     one line or split up one restriction over several lines, e.g.

       $PROGRAM        QUERY.PUB.SYS
         $MODE         5
         $CLASS    4

     The only important thing to remember is that each individual restriction
     must be terminated with a "$CLASS" keyword (or a $FORBID, which we'll
     discuss later).  Thus, you put all the things that define WHO is being
     allowed to access the database first, and then you specify WHAT user class
     he is to be granted.

   - You can have any number of restrictions in the file, and more than one can
     specify the same user class; e.g.  our file could also have been

       $USER BOSS.AP                                $CLASS 10
       $USER @.AP  $PROGRAM APMAIN.PUB.AP           $CLASS 7
       $USER @.GL  $PROGRAM GLAPLINK.PUB.GL         $CLASS 7
       $USER CLERK.AP AUDIT.AP  $MODE 5 6 7 8       $CLASS 5
       $PROGRAM QUERY.PUB.SYS  $MODE 5              $CLASS 4
       $USER @.AP                                   $CLASS 3

     in which case, all AP users running APMAIN.PUB.AP and all GL users running
     GLAPLINK.PUB.GL would have been granted access in user class 7.

   - If a user satisfies none of the given restrictions, he is entirely
     forbidden from using the database.  If you want to set up a "default" user
     class, which all not-otherwise-authorized users will use, you can just add
     a line

       $USER @.@.@       $CLASS 1


Calling the "VEOPEN" procedure from your programs ``contents
Calling the "VEOPEN" procedure from your programs

Once you've set up the access control file, you have to make sure that all
programs that want to access the database call our VEOPEN procedure instead of
DBOPEN.  This is done differently on the Classic (non-Spectrum) machines and in
Native Mode on Spectrum (MPE/iX) machines; if you're on a Spectrum and want to
call VEOPEN from your Native Mode programs, please see the Calling 'VEOPEN'
From Your Native Mode Programs chapter.


MPE/V and MPE/iX differences: calling VEOPEN in CM
you're on a Classic machine or are on a Spectrum but want to call VEOPEN
from your Compatibility Mode programs, this chapter is for you.

We make this requirement since we don't want to change your existing IMAGE
software by replacing HP's DBOPEN with our version; in fact, it's quite easy
for you to convert your programs from DBOPEN to VEOPEN.  (Note that if you use
VEOPEN to open a database that doesn't have an access control file, VEOPEN will
behave exactly the same as DBOPEN; that way, it's always safe to change your
programs to call VEOPEN.)

First, the syntax of VEOPEN is exactly the same as DBOPEN.  You call it by
saying


COBOL calls to VEOPEN

  CALL "VEOPEN" USING DB-NAME, PASSWORD, MODE, STATUS.   [COBOL]


FORTRAN calls to VEOPEN

  CALL VEOPEN (DBNAME, PASSWORD, MODE, STATUS)           [FORTRAN]


PASCAL calls to VEOPEN

  VEOPEN (DBNAME, PASSWORD, MODE, STATUS);               [PASCAL]


SPL calls to VEOPEN

  VEOPEN (DBNAME, PASSWORD, MODE, STATUS);               [SPL]

The password may be specified if one of your restrictions in the access control
file depends on the password (see below); although we allow this, most people
usually don't use it -- if you don't, you can pass anything as PASSWORD, and it
will be ignored.  All other parameters are identical to DBOPEN's, so a simple
/CHANGE command (or an MPEX '%EDITCHG @.SOURCE, "DBOPEN","VEOPEN") can change
your programs to use VEOPEN.

Note that in our VEOPEN installation job stream (see "Installing VEOPEN",
below), we declare VEOPEN to be a system intrinsic, which is especially useful
if you'll be calling it from PASCAL or SPL.  If you ever find the "INTRINSIC
VEOPEN;" or "PROCEDURE VEOPEN; INTRINSIC;" statement giving you a compiler
error, look in the INSTALLING VEOPEN section -- it'll give you some advice.

MAKING PROGRAM WHICH SOURCE YOU DON'T HAVE CALL VEOPEN


Making program which source you don't have call VEOPEN ``contents
Making program which source you don't have call VEOPEN

For some programs -- like QUERY, QUIZ, QUICK, etc.  -- you can't just change
the source code because you don't have the source code.  No problem! We allow
you to change the program file directly, by just doing a


PATCH, VEOPEN.PUB.VESOFT entry point

   :RUN VEOPEN.PUB.VESOFT,PATCH

entering the filename to be changed (e.g.  QUERY.PUB.SYS), and then responding
"V" when asked

   Change it to call (V)eopen, (D)bopen or (N)o change at all? V

Let me emphasize that this is an utterly harmless change.  All we do is change
the program to call VEOPEN in place of DBOPEN; since VEOPEN's parameters are
exactly the same as DBOPEN's, the program will work just as before, except that
it'll be able to access a database secured using VESOFT's IMAGE security
system.

When VEOPEN is installed, by the way, we automatically make a copy of
QUERY.PUB.SYS as the file QUERY.PUB.VESOFT and change it to call VEOPEN.  After
you convert your database to use VEOPEN, you can run QUERY.PUB.VESOFT to see
how identical it is to the normal QUERY.  Since VEOPEN of a database that
doesn't have an access control file is exactly the same as a DBOPEN, you'll be
able to use any converted program to access any database, whether secured by
our system or not.

If you should for some reason want to change your program back to call DBOPEN
instead of VEOPEN, just respond with a "D" to the

   Change it to call (V)eopen, (D)bopen or (N)o change at all? D

question, and the program will be changed back to exactly what it was before
you changed it to call VEOPEN.


SL segments, patching them to use VEOPEN
, you can even patch SL's this way.  Just enter the name of the SL
when asked for the filename; VEOPEN will then ask you what segment you'd like
to patch.  Enter the segment name (not the procedure name), and VEOPEN will
patch it just as it would patch a program.

CHANGING YOUR ENTIRE APPLICATION SYSTEM TO CALL VEOPEN


Changing your entire application system to call VEOPEN ``contents
Changing your entire application system to call VEOPEN

For most people, the biggest problem in switching to VEOPEN is simply changing
their programs.  Actually, this isn't a major problem at all, since VEOPEN is
just like DBOPEN and no source code changes are required except for changing
the string "DBOPEN" to "VEOPEN".  In fact, using VESOFT's MPEX, this is even
easier.

Using MPEX, you can simply say

   %EDITCHG @.SOURCE.AP, "CALL DBOPEN","CALL VEOPEN"

and have it change (using EDITOR/3000) all occurrences of the string "DBOPEN"
(which should only be in CALL statements) to "VEOPEN" in all your SOURCE.AP
source files.  After changing the sources, you can then recompile your entire
system with an MPEX command such as

   %COBOL @.SOURCE.AP, @.PUB.AP

(see the MPEX User Manual for more details).

Changing entire filesets of program files is just as simple.  MPEX has a
special command to do this called VEOPENCH:


VEOPENCH

   %VEOPENCH @.PUB.AP(ISCMPROG)

This will change all program files in PUB.AP that call DBOPEN to call VEOPEN
instead.  Those that don't call DBOPEN won't be affected at all.

To switch a fileset from VEOPEN back to DBOPEN (should you ever want to do
this), add the option ";REMOVE" to the "%VEOPENCH" command:


REMOVE, option for MPEX's VEOPENCH command

   :RUN MAIN.PUB.VESOFT;INFO="VEOPENCH @.PUB.AP(ISCMPROG);REMOVE"

If you aren't an MPEX customer, the SECURITY tape that includes VEOPEN has a
trial copy of MPEX, good for a month or so after installation.  If it still
hasn't expired, you can execute the above commands.  If it has expired, you can
still change your programs one by one.

CALLING VEOPEN FROM YOUR NATIVE MODE PROGRAMS


Calling VEOPEN from your Native Mode programs ``contents
Calling VEOPEN from your Native Mode programs


MPE/V and MPE/iX differences: calling VEOPEN in NM
you want your Native Mode Spectrum program to use VEOPEN instead of DBOPEN,
just link it with ;XL=VEOPENNL.PUB.VESOFT:

   :LINK FROM=MYOBJ;TO=MYPROG;XL="VEOPENNL.PUB.VESOFT"

Whenever MYPROG tries to call DBOPEN, it will actually call our own procedure
called "DBOPEN" from VEOPENNL.PUB.VESOFT; this procedure will then call VEOPEN
and do all the VEOPEN things.


QUIT with parameter -1041 when using VEOPEN

(Note that you still need to add the VEOPEN segment to the Compatibility Mode
system SL using VEPROC.JOB.VESOFT, as discussed in "Installing VEOPEN", below
-- if you don't, you'll get an abort with PARM = -1041.)

What if you don't have the object file (pre-:LINK) of this program, but only
have the program file? No problem; you should simply :RUN the program with
;XL=VEOPENNL.PUB.VESOFT, e.g.


VEOPENNL.PUB.VESOFT, VEOPEN NL file for MPE/iX``Spectrum
VEOPENNL.PUB.VESOFT, VEOPEN NL file for MPE/iX

   :RUN MYPROG;XL="VEOPENNL.PUB.VESOFT"

You must specify the ;XL= parameter either on the :RUN or on the :LINK -- if
you omit it from both, your program will continue to call the real DBOPEN
(rather than VEOPEN).  No patching or source code modifications are necessary.

Finally, note that if you call DBOPEN not from your program but from one of
your XLs, you can still change that into a VEOPEN call.  Just be sure that you
specify VEOPENNL.PUB.VESOFT as the LAST filename in the ;XL= list, e.g.

   :LINK FROM=MYOBJ;TO=MYPROG;XL="MYNLA,MYNLB,VEOPENNL.PUB.VESOFT"


What you should do about your database passwords ``contents
What you should do about your database passwords

VEOPEN enforces the restrictions you've specified in your access control file.
What prevents someone from bypassing VEOPEN and using a normal DBOPEN call to
access your database?

The final, key step in protecting a database using this security system is to
change all the passwords.  Once they're changed, nobody (except for possibly,
but not necessarily, the database creator) will know them; furthermore, if
somebody learns them, you can instantly change them again.

There are two ways to change your database passwords:

   - You can use DBUTIL's SET PASSWORD command:

       :RUN DBUTIL.PUB.SYS
       >>SET dbname PASSWORD class# = password

     You should change the passwords of all the user classes that are mentioned
     in your access control file.


DBPROTECT, VEOPEN.PUB.VESOFT entry point

  - Or, even better, you can use VEOPEN.PUB.VESOFT's DBPROTECT entry point to
     automatically set all the database passwords to random values.  You'll
     still be able to determine these passwords, if you really need to, by
     logging on as the database creator (or with SM) and doing a DBUTIL >>SHOW
     PASSWORDS; you'll still always be able to access the database as the
     database's creator by using the password ";".

     However, everybody except for you, the database creator, will only be able
     to access the database through VEOPEN since other users will never know
     what these random passwords are.  Just in case, you can periodically (even
     every day!) re-scramble all the passwords and never have to change any
     program or even the access control file.

     The way to do this is to say:

       :RUN VEOPEN.PUB.VESOFT,DBPROTECT
       Enter the name of the database to be PROTECTED: MYBASE

     This will set all 63 passwords of the MYBASE database to random values,
     and thus prohibit any access to the database except using VEOPEN (or, of
     course, by the database's creator using the ";").


The exact syntax of a VEOPEN access control file (ACF) ``contents
The exact syntax of a VEOPEN access control file (ACF)

Earlier, we discussed what an access control file generally looks like.  Here
we'll show the exact syntax of an access control file and all the things that
you can do with it.

   * An access control file is a sequence of restrictions, each of which
     specifies a number of criteria (e.g.  user, program, mode, or password)
     followed by a $CLASS or $FORBID keyword.  This keyword indicates what
     action will occur for someone who satisfies these criteria.

   * The criteria consist of one or more of the following, given in any order:


USER, VEOPEN ACF keyword
$USER, VEOPEN ACF keyword

      - $USER userID [userID ...]

         e.g.  $USER  JOE,@.AP  MGR.AP,DATA  CLERK.GL

         This means that this restriction pertains to anybody with one of the
         given user IDs.  A user ID may contain a session name, user name,
         account name, and/or group name, using the usual format from the
         :HELLO command:

            [session,]user.account[,group]

         The session name and group name may be omitted, meaning any session
         and any group; wildcards (@, #, ?) can be used in any part of the user
         ID.  A special case is that if the session name is omitted but the
         comma before the user ID is still specified, this refers to anyone
         with no session name, as opposed to anyone with any session name
         (which is done if both the session name and the comma are omitted).

         Thus, our example "$USER  JOE,@.AP  MGR.AP,DATA  CLERK.GL" refers to

           - Anybody with session name "JOE" logging on as any user in the "AP"
             account, or

           - The user "MGR.AP" logging on into group "DATA", or

           - Someone with no session name logging on as "CLERK.GL".


PROGRAM, VEOPEN ACF keyword
$PROGRAM, VEOPEN ACF keyword

      - $PROGRAM program [program ...]

         e.g.  $PROGRAM  AP000@.PUB.AP  APLOOK.PUB.AP

         This refers to a user running one of the given program files.  Each
         program file may include wildcards, like @, # or ?; our example means
         "a user running either the program APLOOK.PUB.AP or any program in
         PUB.AP whose name starts with AP000".


MODE, VEOPEN ACF keyword
$MODE, VEOPEN ACF keyword

      - $MODE mode [mode ...]

         e.g.  $MODE 5 6 7 8

         This refers to somebody trying to open the database in one of the
         given DBOPEN modes (1 through 8).  A common example is "$MODE 5 6 7
         8", which means someone who's trying to read the database; other cases
         might be

           - $MODE 1 2 4 5 6 8

             which means anybody not using the exclusive modes 3 or 7, i.e.
             anybody who's accessing the database non-exclusively.

           - $MODE 5 6 8

             which means anybody trying to do non-exclusive reading.


PASSWORD, VEOPEN ACF keyword
$PASSWORD, VEOPEN ACF keyword

      - $PASSWORD password [password ...]

         e.g.  $PASSWORD SECRET FROB

         This refers to somebody who's specified one of the given passwords in
         the VEOPEN call.  This allows you to be even more selective with your
         security, allowing the same user running the same program to access
         the database in different ways depending on the password given in the
         VEOPEN call.  To keep these passwords secret, you can put a
         restrictive file security mask (e.g.  R,W,A,L,X:CR) on the access
         control file, which will let VEOPEN look at it but not anybody else.

         Most people prefer to avoid database passwords entirely and rely
         solely on the user, program, and mode restrictions, since that usually
         gives you the best security; in that case, the password passed to
         VEOPEN is ignored.  Still, you can use $PASSWORD if you really want
         to.

   * The criteria must be followed by one of the following keywords:


CLASS, VEOPEN ACF keyword
$CLASS, VEOPEN ACF keyword

      - $CLASS classnum

         e.g.  $CLASS 10

         This means that anybody who satisfies the criteria will be given
         access to the database in the given IMAGE user class.  Of course, it's
         the user class that dictates exactly what a user will be able to
         access within the database.


FORBID, VEOPEN ACF keyword
$FORBID, VEOPEN ACF keyword

      - $FORBID

         This simply means that anybody who satisfies the criteria won't be
         able to access the database at all.  This is the default for anybody
         who doesn't satisfy any of the criteria in any of the restrictions
         specified in a file, but you might use it to specifically forbid
         access by certain users or certain programs that would otherwise
         satisfy one or more of the criteria.

   * Any number of restrictions can be specified, each consisting of one or
     more criteria followed by a $CLASS or a $FORBID.  The file is completely
     free-form, which means that you can have any number of spaces between
     tokens, and can split any criterion or restriction across line boundaries
     if you want to.  The only thing you can't do is insert spaces into a
     keyword ($USER, $PROGRAM, etc.) or a user specifier, program name,
     password or user class or to split one of those across lines.

   * Note how the various parts of criteria are logically combined.  Whenever
     you specify several values for one keyword (e.g.  "$MODE 5 6 7 8"), this
     is an "or" combination -- it means someone accessing the database in modes
     5, 6, 7, or 8.  However, when you specify several keywords in one
     restriction (e.g.  "$USER @.AP $PROGRAM FOO.PUB.SYS"), this is an "AND"
     combination -- it means anyone who both has a user ID matching @.AP AND is
     running the program FOO.PUB.SYS.

   * Finally, remember that if more than one restriction is matched, the first
     one is the one used.  This means you ought to put the more specific
     restrictions first, followed by the more general ones, which are used if
     none of the previous ones are satisfied.

For example, consider the access control file "MYBASEVE.DATA.TEST", which is
the access control file for the database "MYBASE.DATA.TEST".  It looks like:

   $USER DBA.TEST MGR.TEST MANAGER.SYS           $CLASS 50
   $USER @.TEST  $PROGRAM MYPROG.PUB.TEST        $CLASS 40
   $PROGRAM QUERY.PUB.SYS  $USER @.DEV @.TEST,JOB
                                 JACK,@.TEST JILL,@.TEST
                           $FORBID
   $USER @.TEST  $PROGRAM MISCINQ.PUB.SYS  $MODE 5 6 8
                 $PASSWORD LOOK            $CLASS 33
   $PROGRAM MYPROG.PUB.TEST                $CLASS 20
   $USER PETE,@.@                          $CLASS 5

What does it mean?

   - The users DBA.TEST, MGR.TEST, MANAGER.SYS (any session names, any group
     names) get access in user class 50.

   - Any other user in the TEST account who's running the program
     MYPROG.PUB.TEST will get access in class 40.  It's quite likely that
     MYPROG.PUB.TEST always needs class 40 to access the data that it has to
     work with, but imposes its own security restrictions that make sure that
     its users do only those things that it's appropriate for them to do.

   - Access using QUERY is forbidden to any user in the DEV account, any user
     logged on into the JOB group of the TEST account, and also to any users in
     TEST with session names JACK or JILL.  Note that DBA.TEST and MGR.TEST
     aren't restricted by this since they're automatically allowed to access
     the base in class 50 by a previous restriction.  Also note that we've
     split this line onto more than one record, and exchanged the order of
     $PROGRAM and $USER.  (We believe in individual freedom.)

   - Any user in the TEST account who's running the program MISCINQ.PUB.SYS can
     access the database in class 33 provided the program is opening the
     database in modes 5, 6 or 8 (read-only, non-exclusive) AND passes the
     password "LOOK" in the VEOPEN call.  MISCINQ might, for instance, be a
     program that prompts the user for a password, and passes it on to VEOPEN
     (it wouldn't make much sense to put in the $PASSWORD keyword if MISCINQ
     always gave the same password).  Since you have a $PASSWORD keyword, you
     should secure the access control file itself by doing

       :ALTSEC MYBASEVE;(R,W,A,L,X:CR)

     to allow creator-only access to the file.

   - Any user anywhere who's running MYPROG.PUB.TEST will get access in class
     20; again, remember that any user in the TEST account always gets class
     40, and MANAGER.SYS always gets class 50.  That's how you say "give class
     20 access to all users except for @.TEST" -- you first set up a
     restriction for @.TEST, and then for everybody else, and the first
     restriction takes precedence for the @.TEST users.

   - Anybody logging on anywhere with session name PETE, running any program,
     using any access mode, and specifying any password, will get class 5.

   - Finally, anybody who's not covered by any of these restrictions won't be
     allowed to access the database at all.


Installing VEOPEN ``contents
Installing VEOPEN


VEPROC.JOB.VESOFT, installing VEOPEN
you will probably want VEOPEN to be called by anyone in the system,
you'll want to stream the job stream VEPROC.JOB.VESOFT to put it into the
system SL (you'll have to re-stream it every time you get a new version of
MPE).  This won't damage your system at all, nor will it cost you anything in
the way of system resources -- it will just make VEOPEN available to any
program in the system that needs to use it.

Note: this job also adds the VECMMND, VECHECKLOGON and MPEXHOOK procedures to
SL.PUB.SYS.  See "What If Your Program Does A :STREAM Using The COMMAND
Intrinsic?" in Batch Security and Job Stream Programming and "Checking SECURITY
Logons From Within Your Program" Logons From Within Your Program" in Logon
Security in this manual, and "MPEX HOOK" in the chapter on Running MPEX of the
MPEX User Manual for more details.

If for some reason you're hesitant to add VEOPEN to the system SL, (and you are
not using Native Mode programs on MPE/iX) you can use SEGMENTER to add our
segments to SL of your own in some group and account; then, VEOPEN will be
callable from all programs in that group and account (or the entire account if
the group is PUB), as long as you run the program with ;LIB=G (or ;LIB=P, if
the group is PUB).  Use VEPROC.JOB.VESOFT as an example of how to do this.

The trouble with adding VEOPEN to a group or PUB group SL is that the group
containing the SL will then have to have PM capability.  Also, in order to use
VEOPEN with Native Mode programs on MPE/iX, you must add our segments to
SL.PUB.SYS.  All in all, most of our users find that it's better to add VEOPEN
straight to SL.PUB.SYS.

Remember that installing VEOPEN into your system SL doesn't automatically
secure your databases -- to do this, you have to build an access control file,
change your programs to call VEOPEN and then either change your database
passwords manually or :RUN VEOPEN.PUB.VESOFT,DBPROTECT.  Also, any program
files like QUERY, QUIZ, etc.  that call DBOPEN will still have to be changed
using :RUN VEOPEN.PUB.VESOFT,CHANGE if you want them to call VEOPEN directly
without having to have the user know the database password.


The VEOPEN "INSTANT DEMO" ``contents
The VEOPEN "INSTANT DEMO"

If you want to see a quick example of VEOPEN in action, do the following:

      :HELLO VEDEMO,MANAGER.SYS
      :RUN QUERY.PUB.VESOFT; LIB=P
      >BASE=VEOPNT.DEMO.VESOFT
         (when prompted for password, type anything)
         (when prompted for mode, type 5)

As you can see, QUERY.PUB.VESOFT lets you access your database WITHOUT
specifying a password.  This is because:

   1. QUERY.PUB.VESOFT is a copy of QUERY.PUB.SYS that has had
      VEOPEN.PUB.VESOFT,PATCH run against it;

   2.  SL.PUB.VESOFT contains the VEOPEN procedure;

   3. When you installed SECURITY, our installation procedure automatically
      created a file called VEOPNTVE.DEMO.VESOFT.  This file includes the line:

         $USER VEDEMO,MANAGER.SYS $PROGRAM QUERY.PUB.VESOFT
               $MODE 5 6 7 8 $CLASS 1

The VEOPNTVE.DEMO.VESOFT file indicates that:

   * somebody who's logged on as VEDEMO,MANAGER.SYS,

   * who's running the program QUERY.PUB.VESOFT,

   * and who's trying to access the VEOPNT.DEMO.VESOFT database in mode 5, 6, 7
     or 8

   * will be able to access the database in user class 1.

You might also try to:

   - log on to some other logon (e.g.  MANAGER.SYS without the VEDEMO session
     name) -- you won't be allowed to access your database without specifying a
     password.

   - Try accessing the database in some other mode (e.g.  mode 1) -- again, you
     won't be allowed to.

   - Try using any other program (even another program that's been changed to
     call VEOPEN) -- you still won't be able to access the database unless the
     VEOPNTVE.DEMO file explicitly permits it.

Note, however, that in order to truly use VEOPEN in your application systems,
you ought to stream VEPROC.JOB.VESOFT to install VEOPEN into the system SL.
The copy of VEOPEN that we have in SL.PUB.VESOFT can only be used by programs
(such as our QUERY.PUB.VESOFT) that are kept in the VESOFT account.

The following is a list of everything that we believe could be considered an
"incompatibility" with the previous major release of SECURITY.  We don't
believe any of these changes should have a major negative impact on you, but we
wanted to make you aware of them.  For more details on any of these features,
please see the main entry for that feature in the SECURITY User Manual.

  *  %ABORTJOB SCHED CAN ABORT STREAMX SCHEDULED JOBS

The scope of the SCHED job attribute has been extended to encompass both MPE
scheduled jobs and STREAMX scheduled jobs (STREAMX SCHEDULING features --
repetitive and conditional job submission -- are described in the SECURITY
MANUAL).

As a result of this change, issuing the MPEX command %ABORTJOB SCHED will now
result in the loss of all STREAMX scheduled jobs (including the specification
of when the job is to be launched).

If you wish to limit the scope of SCHED to MPE scheduled jobs only, you should
use the MPEX command %ABORTJOB @J&SCHED instead.

When the ABORTJOB command is issued from the %SEC prompt, the scope of the
command is automatically limited to STREAMX scheduled jobs.

Type "%HELP ABORTJOB" or "%SEC HELP STREAMX" for more details on this topic

  *  %BACKG STOP, HELLO TURNS OFF HELLO TRAP

The BACKG HELLO task was first introduced in a limited fashion with late 2.4
releases.  One aspect has been changed with this release: using the %BACKG
STOP,HELLO command to stop execution of the BACKG HELLO task now also turns off
the HELLO trap.

This means that the BACKG HELLO task and the HELLO trap will now be turned on
and off together, simplifying administration of the HELLO trap.

                      *** END OF SECURITY DOCUMENT ***