xenmenu 0.8b
1 Feb 1998

Table of Contents

Description of xenmenu
Installing xenmenu
Using xenmenu
Securing xenmenu
Programming Menus
Contacts

Description of xenmenu

Welcome to xenmenu 0.8b. This program is a highly customizable, text-based menu generator for UN*X systems. With xenmenu, users have an easy-to-understand yet flexable menu programming language with which to create pleasing menus quickly and easily. These menus, stored as plain ASCII files, can be modified on the fly and reinstalled without having to recompile anything or halting xenmenu while reconfiguring. Xenmenu can also be used as a secure user shell (See Securing).

This is the first BETA release of xenmenu. Although the code is now stable enough to move out of the ALPHA stage, there are still probably bugs, the installation process is not as easy as if could be, and the documentation may not be complete.

Installing xenmenu

Xenmenu was written on and for the Linux operating system, but should compile and run on most any UN*X system with an standard C compiler. It has been tested on BSDI 3.1 and Solaris 2.5.1 systems. To compile xenmenu on your system, follow these steps:

A. Quick Install

There is a script called install.sh that will allow you to configure and install xenmenu and all of the support programs. This script is not tested really and is not as rhobust as it should be. It is suggested that you follow the Detailed Install instructions instead.

B. Detailed Install

1. Visit http://www.cs.purdue.edu/homes/steinkf/programs/xenmenu to get the latest version.
2. Unpack the source somewhere on the system that will be used to compile it. If you downloaded xenmenu-0.8b.tar.gz, entering

          gzip -d -c xenmenu-0.8b.tar.gz | tar xf -

   should decompress the package. If you downloaded xenmenu-0.8a.tar.Z, then

          uncompress -c xenmenu-0.7b.tar.Z | tar xf -

   should decompress the package.

   After unpacking the source, you will have a directory called xenmenu-0.8b. Change into that directory, (e.g. type cd xenmenu-0.8b).

3. Run the configure script, (type ./configure).
4. Edit config.h (optional) and change any of the options that you want to. All of the options are documented in detail within the file.
5. Edit get_input.h (optional) and change any of the options that you want to. All of the options are documented in detail within the file.
6. Edit Makefile and change anything necessary.
7. Type make. There should be no warnings or errors, (if there are, please send a note to the contact listed under Contacts).
8. If there are no errors or warnings generated in the last step, type make install to install the menu program into the directory specified in Makefile. You may also run xenmenu from the directory you compiled it in. If you want to do that, skip this step.
9. Make sure the default menu and menu home directory as defined in config.h, (if any), exist and you are ready to start writing your own menus (See Programming).

NOTE: The directory contrib contains some sample programs that you may find useful. Please see the README in that directory for more information. There are also sample menus and text files in the sample_menus and sample_text directories.

Using xenmenu

Xenmenu can be called simply by typing menu in which case it will attempt to load and run the default menu as defined in config.h. To run a menu besides the default one, just run xenmenu as menu <menufile> where <menufile> is the name of the menu you want to run. If <menufile> resides in any directory besides the menu home, (as defined in config.h), or the current directory, you must include a pathname to <menufile>. If security is set so that only menus in a certain directory may be loaded, then you will not be able to load menus under any other directory tree. If multiple <menufile> arguments are given, then only the first valid menu found is used.

You may also call menu with the -h argument to get a help description, or with the -v argument to get a version statement. If the -h or -v arguments appear anywhere on the command line, than the first instance of either argument is executed and no menu is loaded, (even if a menu file is given).

If no MAINMENU is defined in the config.h file, then you must supply menu with the name of a menu to load.

Environment variables may be set within various configuration files that xenmenu parses when loading. The names of these files are defined in config.h, (USERCONFIG, SYSCONFIG, and SECURECONFIG). The format of these files are:

ENVIRONMENT_VARIABLE VALUE

The ENVIRONMENT_VARIABLE is the name of the environment variable that you want to set, (e.g. EDITOR), and VALUE is the value you want to set it to, (e.g. /bin/vi). If VALUE is not given, then ENVIRONMENT_VARIABLE is cleared. The configuration files, (if defined in config.h), are parsed in the following order: SYSCONFIG, USERCONFIG, SECURECONFIG. This means that if an environment variable appears in more than one of the configuration files, the last file to be parsed which contains the definition is what the variable will be set to.

Programs may also be run from within the configuration files by using the following format:

run PROGRAM

The PROGRAM is the name of the program that you want to execute. If SECURERUN is defined in config.h, then PROGRAM must reside under that directory. Otherwise, PROGRAM should reside somewhere in the PATH environment variable, or a full path name should be given.

Securing xenmenu

Since xenmenu is very flexable about what it can do and files it can run, a security flag has been added (See config.h) to lessen the damage a user can do to to others. For example, suppose a user put the following line in a menu:

run rm -rf ~

Whenever someone ran that menu, their home directory would be erased which is probably not wanted. To avoid problems like this, three directories are defined in config.h: SECURERUN, MENUDIR, and VIEWDIR. A SECURE flag is also set in config.h that defines the level of security you want compiled in to xenmenu. The value SECURE can take are integers between 0 and 7. The following is a breakdown of the security levels:

    0 - No security checks.
    1 - Only files in SECURERUN may be run (symbolic links are OK).
    2 - Only menus in MENUDIR may be loaded.
    4 - Only files in SECUREDIR may be read.

SECURE may be any of these numbers or the sum of any. For example, a value of 7 (4 + 2 + 1) stands for full security.

It is important to keep in mind that files loaded or accessed securely will automatically take a path as set by SECURERUN, MENUDIR, or SECUREDIR. This means that file declaration must be from that path. For example, take the following run command:

run /bin/ls

If SECURERUN is set to /usr/lib/menu/bin, then the above run command will try to run /usr/lib/menu/bin/bin/ls which is probably not the desired file. What you would do is make a symbolic link to /bin/ls from the SECURERUN directory and change the above line to:

run ls

Another security feature is the ability to set environment variables for users running xenmenu that they cannot change with their own configuration file. This is enabled by defining a SECURECONFIG in config.h and creating the file that SECURECONFIG points to. The SECURECONFIG file is parsed after the USERCONFIG and SYSCONFIG files, so any values that are set by them will be overwritten, (See Usage).

Programming Menus

Menu files are plain text files that contain certain options and arguments. Comments can be inserted into the menu file by inserting a # character as the first character on the line. Blank lines are ignored. Sample menus may be found in the sample_menus directory.

The following is a list of all the commands you can include in a menu file and a description of what that command does. Options in <> marks are required arguments while ones inside [] marks are optional.

    checkcase                Turns on case sensitive checking for input.  This
                             means that an option 'p' will be different than an
                             option 'P'.  This must be defined BEFORE any
                             options are defined.
    nocheckcase              Turns off case sensitive checking for input.  This
                             is the default.
    center       <string>    Centers the given string on the screen.  The string
                             will be "word-wrapped" as needed.
    columns      [number]    Sets the number of columns to print options in to
                             [number].  You can change columns within the menu so
                             some options are printed one way and others another.
                             If [number] is not defined, then 1 column is used.
    header       [header]    Defines the menu header to be [header].  If header
                             is blank, then MENUHEAD as defined in config.h is
                             used.
    name         [name]      Defines the menu name to be [name].  If [name] is
                             blank, then [name] is cleared.
    print [-n]   [string]    Prints [string] to the screen.  If no string is
                             defined, a blank line will be printed.  If [string]
                             contains something between '' marks, it is taken as a
                             command to be run.  To print a ' character, enter it
                             as ''.  Environment variables may be printed by
                             preceeding them with a $ mark.  To print a $
                             character, enter it as $$.  If the -n argument is
                             given, than a newline is not appended to the end of
                             [string].  Usually, all leading spaces and tabs are
                             removed from [string] before it is printed to the
                             screen.  In order to print leading spaces, begin the
                             string with a double quote.  Any double quotes within
                             the string are treated as literals and printed to the
                             screen.  A double quote found at the end of a string,
                             if the string begins with a double quote), is not
                             printed, however.  A double quote may also be used if
                             you want to print a -n at the begining of the string.
    printfile    <file>      Prints the <file> to the screen.  If SECURE,
                             (defined in config.h), is > 4, then the path to
                             <file> is taken from SECUREDIR, otherwise <file>
                             should contain a path.
    printheader              Prints the menu header.  The [header] will be
                             printed on the left side of the screen and the
                             [name] on the right side.  A default header value,
                             defined in config.h is used if header is not
                             defined.  No name is printed if not defined.
    printline    [string]    Prints a line across the screen.  If [string] is
                             not defined, a line of dashes will be printed,
                             otherwise a line composed of [string] will be
                             printed.
    prompt       [string]    Sets the menu prompt to [string].  If [string] is
                             not defined, then DEFAULTPROMPT defined in config.h
                             is used.  NOTE: Everything after the keyword prompt
                             and a space is taken as the prompt, (including
                             spaces).
    run          <file>      Runs the defined file.  If SECURE, (defined in
                             config.h), is a 1, 3, 5, or 7, then the path to
                             <file> is taken from SECURERUN, otherwise <file>
                             should contain a path.

    Menu options are defined as follows:

    option {
       <menu definitions>
    }

    The following menu definitions are recgonized:

    NOTE: At least 1 of file, menu, run, or exit should be used in an option
    declaration.  If more then 1 is given, then the last one defined will be used,
    but only 1 should be defined within an option.

    exit                    This means that the menu will exit if this option
                            is chosen.
    file         <file>     This is the filename that will be read if the menu
                            option is chosen.  If SECURE, (defined in config.h),
                            is > 4, then the path to <file> will be taken from
                            SECUREDIR, otherwise <file> should contain a path.
    menu         <file>     This means that the menu <file> will be loaded if
                            this option is picked.  If SECURE, (defined in
                            config.h), is a 2, 3, 6, or 7, then the path to
                            <file> is taken from MENUHOME, otherwise <file>
                            should contain a path.
    run          <file>     This means that the program <file> will be run if
                            this option is picked.  If SECURE, (defined in
                            config.h), is a 1, 3, 5, or 7, then the path to
                            <file> is taken from SECURERUN, otherwise <file>
                            should contain a path.

    comment      <comment>  This is an optional field which holds a description
                            of the menu item.
    name         <name>     This is the name of the option.
    noprint                 This will cause the option not to be printed to
                            the screen.
    value        <value>    This is an optional field that holds the menu
                            "value" or what you press to access this option.
                            NOTE: Values will be automatically assigned by the
                            menu if none is given.

    Contacts

    All comments, questions, and bug reports can be sent to Karyl F. Stein via
    E-Mail to xenon@xenos.net.
    If you are submitting a bug report, please be sure
    to include the operating system and compiler being used as well as all error
    messages; the more details the better.  Please see the file BUGS for a list of
    known problems.

    If you would like to contribute programs to the xenmenu distribution, please
    contact xenon@xenos.net.