NetBSD/usr.sbin/sushi/sushi.8

.\" $NetBSD: sushi.8,v 1.13 2003/02/14 16:11:36 grant Exp $
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Tim Rightnour
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd January 8, 2001
.Dt SUSHI 8
.Os
.Sh NAME
.Nm sushi
.Nd a menu based system administration tool
.Sh SYNOPSIS
.Nm
.Op Ar quickname
.Sh DESCRIPTION
The
.Nm
tool gives the user a menu of various system administration tasks that
may be performed on the system.  It is designed to be simple enough for a
novice to use, and quick enough to help seasoned users perform more
complex tasks with ease.
.Pp
It is also designed to be easily extended and customizable by the user or
administrator.  The menus themselves consist of a number of flat ascii
files which are parsed by the
.Nm
engine when run.  Commands are actually scripts written by the
administrator, and executed from the menu hierarchy.  It is possible to
have multiple hierarchies, and even ones private to a particular user on
the machine.  These hierarchies are all merged for the user at run-time
into a single menu system.
.Pp
The following option is available:
.Bl -tag -width "quickname"
.It Ar quickname
This option allows the user to jump directly to a known submenu or function
within
.Nm "" .
It can be used to avoid the need to navigate deeply nested menus, when the
end destination is known.
.El
.Sh ENVIRONMENT
The following environment variables are used by
.Nm "" :
.Bl -tag -width "PKG_PATH"
.It Ev LANG
Determines the user's current language setting.
.It Ev PKG_PATH
This is the default URL for binary packages used when fetching lists
of packages available to download.  It is also used when actually
downloading those packages.  It defaults to:
ftp://ftp.netbsd.org/pub/NetBSD/packages
.El
.Pp
There may be other environment variables used by various scripts in the
.Nm
menu hierarchy.  This manual page cannot account for those environment
variables, however they should be detailed in the help files for each menu.
.Sh FILES
.Bl -tag -width "sushi"
.It Pa /etc/sushi.conf
This file is used by sushi to override the default locations searched for
menu hierarchies.  It consists of a keyword, followed by instructions.
To override the default searchpaths in
.Nm
you would issue the keyword
.Sq searchpath
followed by a directory name, one per line, that will be searched, in order,
for menu hierarchies.  Each directory name must be preceded by the
.Sq searchpath
keyword. It is not an error to have a non-existent directory listed in
this file, as they will simply be skipped over.  The default list of
directories searched is printed below, in order:
.Pp
.Bd -unfilled
.Pa /usr/share/sushi
.Pa /usr/pkg/share/sushi
.Pa /usr/X11R6/share/sushi
.Pa /etc/sushi
.Pa $HOME/sushi
.Ed
.Pp
The
.Pa $HOME/sushi
path, is always searched, and does not need to appear in
the
.Pa /etc/sushi.conf
file.  The
.Pa /etc/sushi.conf
file will not be parsed for environment variables such as $HOME, so it
would likely be an error to include it there.
.Pp
The
.Pa /etc/sushi.conf
file may also include key bindings, which will override the default use
of function keys in
.Nm "" .
These may be desired in situations where function keys are not available, or
are not desirable because of a window-manager binding.  The format for
binding a key is:
.It bind F1 ^T ^T=Help
In the above example, we have rebound the
.Sq F1
key to Control-T.  The final keyword is the message that will appear at the
bottom of your screen, to remind you which keys are bound to which
functions.  There can be no whitespace in the key description.
The syntax of the new key binding must either be an ascii character
preceded by a caret
.Dq ^
to signify a control modifier, a function key, such as
.Sq F9
or a single ascii character.  It is not possible to bind Alt or Meta keys,
nor is it possible to bind a modified function key, such as control-F1.
.El
.Sh EXAMPLES
Most of the actual usage of
.Nm
is documented in the internal help files, such as commands, and keystrokes
that are used to navigate the menus.  There is also full documentation in
the help pages on writing your own menus.  In order to access help, you
may hit the F1 key at any time, and if help is available for the current
menu, it will be displayed.  It is advised that the user read the help
file from the main menu, as it contains most of the navigation, and basic
concepts of the
.Nm
engine.
.Sh SEE ALSO
.Xr rc.conf 5 ,
.Xr intro 8
.Sh HISTORY
.Nm
first appeared in
.Nx 1.6 .
.Sh AUTHORS
.Nm
was written by
.An Tim Rightnour
.Ad garbled@NetBSD.org
and
.An Dante Profeta
.Ad dante@NetBSD.org .
.Sh BUGS
At the time of this writing, there are a number of display glitches
which are currently being worked on.  In addition there are some failure
modes that
.Nm
does not handle well, such as not recieving output from an escript field.
.Pp
At the time of this writing, the F6 option, to display the current command
before running it, does not work.