xenmenu v0.8b
1 Mar 1998
Table of Contents
I....................................................Description of xenmenu
II....................................................Installing xenmenu
A...................................................Quick Install
B...................................................Detailed Install
III....................................................Using xenmenu
IV....................................................Securing xenmenu
V....................................................Programming Menus
VI....................................................Contacts
I. 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 Section IV).
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.
II. 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 one of the following procedures.
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.8b.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 in Section VI).
8. If there are no errors or warnings generated in step 7, 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
Section V).
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.
III. Using xenmenu
Xenmenu can be called simply by typing xenmenu 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.
IV. 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 Section III).
V. 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.
notype Surpresses the printing of the option type, (i.e.
menu, file, etc.) after the option name.
opttail [string] Defines [string] as the string to be printed after
an option value, (it is what seperates the option
value and the option name).
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.
type Prints the option type, (i.e. menu, file, etc.) after
the option name. This is the default.
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.
VI. 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.
