salmon(1) salmon(1)
NAME
salmon - a multi purpose X11 application
SYNOPSIS
salmon [long options]
help print help and exit
lines print line options and exit
print <file>[,label] print configuration file contents
read <file>[,label] read configuration from file
execute <server> <port> [options]
spawn a child process
Panels
-------------
| | | Line and panel numbers should be used if a
| 1 | 2 | specific display order is desired. Lines
| | | are numbered one to six from the top.
-------------
| | | If line and panel numbers are not set and
| 3 | 4 | fewer than 24 lines are defined, they will
| | | be crowded into the low number panels.
-------------
DESCRIPTION
Salmon is a multi function application that can be used in the After-
step Wharf, as a one or four panel window or as a background daemon not
attached to a display. It can respond to LAN requests to launch other
salmon or for the local time. It can monitor power status and tempera-
tures and, if run SUID, shut down when a critical level is reached. If
run by root, it can keep the local host time syncronized to a master
salmon time server. It will display from one to six lines of data in
single panel mode or from one to six lines each in four panels. Each
line is defined at the command line or in a configuration file with a
list of line specific options separated with underscores. They can be
listed in any order.
The -read option takes salmon's configuration from a file. If the file
contains labels, the configuration can be located in several ways. By
using :label, it will come from the global salmon.cfg file
/usr/local/alter/etc/salmon.cfg. If ~label is used it will come from
the personal file $HOME/etc/salmon.cfg, if file[,label] is used, it can
come from a file in the same directory as the executable. Finally
/path/to/file[,label] is an absolute path to the file to be used.
Labels start with a colon and can be any reasonable number of ascii
characters. Any line in a configuration file that starts with a colon
is read as a label. Backslash line continuation can be used in config-
uration files. Lines can be broken at any point except that necessary
white space must come before a backslash.
Salmon responds to key and pointer events in a fashion that varies
depending on configuration. If -clickoff is set, any pointer event at
any window location causes shutdown to be executed, all key events are
ignored. If a pointer or recognized key event occures in a window or
panel of type -phasecalc, the display state changes. If a pointer or
recognized key event occures on a line of type timer, alarm, reset or
elapsed, the status of the line changes. See detailed explanations
under -phasecalc and line types below. If any button or recognized key
event occures on a line that has a -command defined, that command or
Afterstep function will be executed. Recognized keys are ESC,
Backspace, Enter/Return, Space, Up, Left and Right arrow keys and the
top row and keypad number keys. Commands are the last item processed
and will not be executed if the event has already been responded to.
Warning messages are logged to .../salmon.log, error messages are
logged and printed to stderr. The messages contain a reference to the
function where the error occured and a brief summary of what went
wrong. If -logbeep is set, a chirp will sound when a message is
logged.
Using the moon phase graphics and pixmap backgrounds other than peusdo
transparent requires an external graphic manipulating suite such as
ImageMagick. The talking clock requires a speech synthesizer such as
flite or espeak. The volume control function uses mixer, mixerctl or
aumix depending on the OS. Helper commands are searched for using the
locate data base. This should be kept updated. If an external command
is not found, salmon will exit and print a message to stderr and
.../salmon.log. The locate function will not be used if an absolute
address is given.
OPTIONS
The first five options are not parsed by getopt_long_only(3) so the
leading dash is not required.
[-]help
Print global and line options and exit.
[-]lines
Print line options and exit.
[-]print <name[,label]>|<:label>|<~label>
Read options from file <name>[,label], print results to stdout
and exit.
[-]read <name[,label]>|<:label>|<~label>
Read options from file <name> starting at optional [,label] or
read from the system config <:label> or $HOME/etc/salmon.cfg
<~label>.
[-]execute <-exechost=hostname> <-execport=portnumber>
[-execopts=options]
Use a running salmon to spawn a child process.
Must be the first option.
GLOBAL OPTIONS
These options have a global effect. Leading dashes should not be used
in configuration files. At the command line, one dash should be used
for FreeBSD, OpenBSD and Linux and two for NetBSD.
The first two options are used by -execute callers only.
-exechost<=hostname>
Spawn host.
-execopts[=options]
Spawn salmon with options.
-execport<=portnumber>
Set spawn port. This option is used on the server to set the
port to listen at. It's used on the callers with the -execute
option only.
-execstop
Die after spawning. Used on the servers only.
-iconic
Start as an icon.
-withdrawn
Start withdrawn.
-moongraphic
Display the graphic phase of the moon. Single panel mode only.
-daemonize
Run in the background to launch child processes or act as a LAN
time server/client. Does not need to be attached to a display.
-logbeep
Make a noise when a message is written to .../salmon.log.
-powerlog
Log all power state changes to $TEMPDIR/salmon.log. Shift plus
1 key toggles state. The current state will be logged to
salmon.log.
-timelog
Log all time sync requests to $TEMPDIR/salmon.log. Shift plus 2
key toggles state. The current state will be logged to
salmon.log.
-thermlog
Log all temperature state changes to $TEMPDIR/salmon.log. Shift
plus 3 key toggles state. The current state will be logged to
salmon.log.
-execlog
Log all spawn attempts to $TEMPDIR/salmon.log. Shift plus 4 key
toggles state. The current state will be logged to salmon.log.
-clickoff
Execute shutdown at a pointer event. Any button press at any
location in the window executes shutdown with a delay of -click-
time minutes. Click again to pkill shutdown. Overrides any
other button or key press responses.
-thermoff
Execute shutdown at critical temperature level if the critical
zone is displayed.
-poweroff
Execute shutdown at critical battery level if powerstate is dis-
played.
-settime
Set system wall clock to time on the master time keeper. This
is done only once at startup and is always logged to salmon.log.
If the reset fails for any reason, there will be two identical
entries in the log. If it succeeds, the two entries will be
different. Salmon must be run by the super user to use the time
set and adjust functions on client machines.
-clicktime<=minutes> or -clicktime <minutes>
Pointer event shutdown delay. Default is immediately.
-clicksound<=number>
Pointer event shutdown audio file number. Default is none.
-magnify<=x>
Display salmon at x times 64 pixels. This will be the x/y size
of one panel when in four panel mode. Default is 2.
-refresh<=seconds>
Reexamine data after refresh seconds. If not set, a default
will be determined according to display contents.
-phasecalc[=?]
Display current phase of the moon or the next or previous quar-
ters. Use local time or [=?] UTC. Uses the full window or one
full panel in four panel mode. In phasecalc, left arrow and
button 1 events change the display to the time of the previous
quarter, right arrow or button 3 events to the next quarter and
up arrow/button 2 events restore the display to the current
phase. All other events are ignored.
-appname<=name>
The name displayed by the window manager. Default is "Salmon".
An attempt will be made to interpret environment variables that
start with $ and contain only decimal digits and upper case let-
ters. -appname=$DISPLAY would set appname to the value of $DIS-
PLAY if set or "$DISPLAY" if not set.
-position<=<+|->x<+|->y>
Position on the screen. X11 -geometry with a fixed size.
-cmdfile<=/path/to/filename>
If -read is used, initial configuration will be read from
global, personal or named configuration file. -cmdfile will be
used for followup event, execute and timeout commands that start
with a colon. This must be an absolute path name.
-tempdir<=directory>
Used for resizing pixmaps. Default is $TMPDIR if resolved, /tmp
if not.
-datadir<=directory>
Location of sound and pixmap files. Default is
/usr/local/alter/share/salmon.
-display<=host:display>[.screen]
Local or remote host name, display and screen number for X.
Usually not required if display is localhost.
-background<=color>
Replace the default "black" background color. Hex values in
configuration files should have the # replaced with 0x or 0X.
-foreground<=color>
Replace the default "salmon1" foreground color.
-audiocmd<=command>
Replace the default audio command. "cat " in most cases.
-audiodev[=device]
Replace the default audio device. Varies with the OS. The
argument is optional, use -audiodev if the audio command
requires a NULL device.
-thermtime<=minutes>
The delay for shutdown if a critical high temperature is experi-
enced. Default is immediately.
-thermcmd<=command>
Execute user command at thermal shutdown.
-stepfile<=/dir/name>
Afterstep socket location and name. Only needed for executing
afterstep internal functions.
-timeport<=portnumber>
Time server port number. This port is kept open and listening
by the master time server. The client machines poll for the
current time once every -timepoll minutes.
-timehost<=hostname>
LAN time server name. The LAN time server should be configured
to keep accurate time with ntpd, openntpd, a precise clock or
some other means. Using salmon to syncronize a network is only
intended to keep the clocks within a few milliseconds. Testing
with timedc consistently shows variations of less than 10 mil-
liseconds after syncronization has been achieved.
-timepoll<=minutes>
Time client poll rate in minutes. Default is one minute.
-ctlport<=portnumber>
Listen for samcon connections on this port. See "man samcon".
-powertime<=minutes>
Low battery shutdown delay in minutes. Default is immediately.
-powercmd<=command>
Execute user command at low power shutdown.
-talker<=command>
Speech synthesizer command to announce the time. Default is
"flite" if found by "locate bin/flite". If another default syn-
thesizer if prefered, redefine TALKER in salmon.h and recompile.
-unzip<=command>
Pixmap decompress command. Default is "gunzip <".
-resize<=command>
Pixmap resize command. Default is "mogrify -colors 20 -scale".
-tiler<=command>
Pixmap tiling command. Default is "montage -geometry".
-line<=option(s)>
Define one display line. This should be an underscore separated
list of options with arguments in any order.
salmon -line=display setting="|Hit|me|" color=green\
command="echo I\'m hit"
LINE TYPES
These options define displayed line types.
The first group does not accept arguments.
Use -line<=type> or -line <type>.
-memfree
Free memory.
-memused
Used memory.
-memtotal
Total memory.
-swapfree
Free swap.
-swapused
Used swap.
-swaptotal
Total swap.
-swapdevices
Swap devices.
-load1
One minute load average.
-load5
Five minute load average.
-load15
Fifteen minute load average.
-processes
Run queue and processes.
-share
Share memory.
-buffer
Buffer memory.
-cache
Cache memory.
-uphours
Uptime as hhhhh:mm:ss.
-updays
Uptime as ddd hh:mm.
-ostype
Operating system type.
-osversion
Operating system version.
-network
Name of the LAN.
-moonphase
Phase of the moon in text.
-powerstate
Power system status. -warning and -critical set the respective
values which are both required. -sound is an optional audible
signal at the warning level and -sound1 at the critical level.
-color1, -color2 and -color3 specify colors to override the
default green, yellow and red. The warning -sound, if set sig-
nals at AC line dropout and when the battery level drops below
-warning. -sound1, if set signals when the battery level drops
below -critical. If -poweroff is set and salmon is run SUID,
shutdown will be executed at < -critical with -powertime delay.
-color1 indicates AC line operation, -color2 indicates battery
>= -warning, -color3 is used at shutdown and when battery <
-warning.
-volume
Simple volume control on three lines. The top line displays the
left and right levels returned by "mixer vol", "mixerctl out-
puts.master" or "mixer -q". Between them is either an x indi-
cating separate levels or a dash indicating linked levels. An X
event on the line toggles the state. The balance is always
latched on GNU/Linux. The lower two lines are sliders with the
left channel on top and a red bar indicating the current levels.
Use key or pointer events on the sliders to set the levels. The
lines will be placed in one panel which must have three empty
lines.
-display
Display only. -setting=|Other| replaces the default "Display"
with "Other" centered in the panel. This is the default if type
is not specified.
The next group accepts an optional argument.
Use -line<=type[=argument]>
-user
User CPU percent. A numeric argument to user, nice, system,
interrupt or idle limits the splits to one CPU/core (1 - n). No
argument or argument equals zero returns the totals.
-nice
Nice CPU percent.
-system
System CPU percent.
-interrupt
Interrupt CPU percent.
-idle
Idle CPU percent.
-hostname
Local host name, [=?] as a title.
-timer
Egg timer. Expire in [[=days ]hours:minutes:seconds], begin
countdown at startup. Timers also accept an additional time as
a -setting argument which will begin timing at a key or pointer
sequence. Timers can be reset while salmon is running. With
the pointer on the line, pressing ESC, up arrow or button two
enters edit mode for the -timer=value and Backspace, left arrow
or button one for the -setting=value. Left or right clicking a
digit lowers or raises it respectively. The top row or key pad
number keys enter the key value in the digit under the pointer.
Left click on the left most character exits reset mode without a
timeout while a button two/up arrow event on the line begins
countdown with the current value. The new values will replace
the configured values and countdown will commence if
Enter/Return is pressed with the pointer on the left most char-
acter.
-alarm
One time alarm. Expire at or past [=%H:%M] today or [=%H:%M
%y/%m/%d], begin count down at salmon startup. When an alarm is
counting down the display reads "Al mm/dd HH:MM". While salmon
is running, reset state for alarms is entered by first stopping
the count down with a left arrow or button 1 event. The display
will read "Alarm X". From stopped state, enter reset as for
timers. In reset mode the display reads "A mm/dd HH:MM". An
ESC event on the left most character resets the buffer contents
to one hour ahead of the current time, left arrow/button one on
the character exits reset mode without timeout. If salmon is
started without -timer=value or -setting=value, the edit expira-
tion time will be the current time. Date and time are automati-
cally corrected for end of month, end of year and daylight sav-
ing time for the local time zone.
-reset
Resetting alarm. Expire at [=%H:%M] or [=%H:%M %y/%m/%d] and
advance by twenty-four hours or the user specified interval.
Begin count down at salmon startup. The -setting argument as
HH:MM specifies the reset interval. Reset as for timers and
alarms except that button one, left arrow, or backspace allows
editing the reset interval.
-elapsed
Stop watch, [=?] begin timing at salmon startup. Elapsed timers
are controlled with left, up and right arrow keys or with but-
tons. When stopped, the display reads "Elapsed X". Any button
or arrow key starts the timer. While running, up arrow or but-
ton 2 stops the display without stopping the time. With the
display stopped, right arrow or right click starts the display
with the stopped time included, left click or left arrow starts
the display without the stopped time. Up or button 2 changes
the display to read "Clear Ela X?". In this state, left or
right continues timing, up arrow or middle click clears the
timer.
-calendar
One or four panel calendar in local or [=?] UTC. If -linenum is
set, "today" will be at the specified line, else it will be the
top line. Use -setting=4 for four panel mode, -panel=n to spec-
ify the location of the panel in single panel mode or the active
line in four panel mode. Use -color=? to highlight the current
day. Only the first -line=calendar will be used, any others
will be ignored. A key or pointer event on a line will cause
the current date to move to that line.
The last group requires an argument.
Use -line<=type<=argument>>
-format<=[UTC]strftime(3) format>
Display current local or universal time in the specified format.
See the strftime(3) documentation for conversion specifications.
Use -setting=? to announce the time. See below.
-thermal<=number>
Monitor the status of a thermal zone. Requires -warning and
-critical values to be set. The -setting option as =k or =f
changes the default Celsius scale to kelvins or Fahrenheit for
this line only. -color1, -color2 and -color3 specify colors to
override the default green, yellow and red for <= -warning tem-
perature, <= -critical or > -critical temperature. If -thermoff
is set and salmon is SUID, when the temperature exceeds -criti-
cal, shutdown will be executed with -thermtime delay. If -sound
is set, it will play when the zone temperature exceeds -warning,
-sound1 plays at > -critical.
-device<=/dev/device|/mount|interface|host|devinfo>
Generic device specifier. Will be reset to specific type at
startup. The specific devices below may be specified if
desired. -color1, -color2 and -color3 specify colors to indi-
cate current status. If not defined, an up or down arrow or a
question mark will show status.
-devdevice<=/dev/device>
Monitor the presence of a file in the /dev directory. Status is
limited to -color1 or an up arrow if present or -color3 or a
question mark if not.
-mount<=/mount/point>
Monitor the status of a local or network file system. Display
will show -setting if defined or -argument from the right most
right slash if not. If the file system is not found in
/etc/fstab, -color3 or a question mark will indicate current
status. If it's found but not mounted, -color2 or a down arrow
is used. If the file system is mounted, -color1 or an up arrow
will be seen. If a line refers to a network file system, salmon
will use -remotehost to monitor the status of the host computer.
If the host is not returning ICMP_ECHOREPLY packets, salmon will
write "Host $remote for file system $/... is not responding."
to salmon.log when the line is clicked.
-interface<=interface>
Monitor the status of a network interface. Status is -color1 or
an up arrow if up and active, -color2 or a down arrow if up not
active or -color3 or a question mark if down.
-remotehost<=host>
Monitor the status of a remote host computer. Status is indi-
cated by -color1 or an up arrow if resolved and responding,
-color2 or a down arrow if resolved not responding or -color3 or
a question mark if not resolved. The time to wait for an
ICMP_ECHOREPLY packet to return can be set on a per host basis
by adding a comma and the time in seconds to the host name,
(-line=device|remotehost=hostname,ttw). The minimum time is ten
seconds, the maximum is 150, the default is 60 seconds.
-devinfo<=devinfo(8) device>
Monitor the status of a device recognized by FreeBSD devinfo(8).
FreeBSD devinfo.h lists four states for a device:
DIS NOTPRESENT=10, /* not probed or probe failed */
DIS ALIVE=20, /* probe succeeded */
DIS ATTACHED=30, /* attach method called */
DIS BUSY=40 /* device is open */
If a match for the device name isn't found, the display shows
-color3 or a question mark, if the result is DIS BUSY, it shows
-color1 or an up arrow. The other three results are combined
and show -color2 or a down arrow.
LINE SPECIFIC OPTIONS
These options are specific to a single line. Options that don't apply
to the line type are ignored.
Use -line=type[=argument] option option[=argument]...
-line=memfree color=pink command=\
"echo Umm, fishy." setting=percent
-warning<=value>
Power or temperature warning level. Required for -powerstate
and -thermal lines. Change status when power falls below or
temperature rises above -warning level.
-critical<=value>
Power or temperature critical level. Required for -powerstate
and -thermal lines. Change status when power falls below or
temperature rises above -critical level.
-color<=rgb.txt name or six or twelve digit hex value>
Color of this line. May be overridden for power, temperature or
device lines. Default colors are set for power and temperature
lines but not for device lines. Setting -color1 -color2 and
-color3 to the same value disables visible status indication.
-color1<=value>
Safe temperature, AC line or best case device color.
-color2<=value>
Warning temperature, running on battery or mid level device
color.
-color3<=value>
Dangerous temperature, critical or warning battery level or
"missing/unmounted" device color.
-sound<=audio file number|=-numeric label>
Audible warning signal for power or temperature, or timer/alarm
expiration. If the number is less than zero, it will be used as
a label in a configuration or command file. If -cmdfile is set,
the label will be searched for there, if not, the personal con-
fig file will be searched. If a speech synthesizer is found, it
will be executed on the line (with backslash continuation) at
the label. The maximum line length is one kbyte which is more
than the longest paragraph in this man page.
-sound1<=number|=-label>
Critical power or temperature audible signal.
-panel<=panel number, 1 to 4>
Not required, puts salmon into four panel mode if greater than
one. If more than six lines are entered, salmon will switch
into four panel mode. Up to six lines will be placed in each
panel in succession. Use panel and line numbers to specify
desired placement. The -line=calendar and -phasecalc functions
will be placed in the first empty panel. If no panels are
empty, salmon will error exit.
-linenum<=line number, 1 to 6>
Not required, lines will be assigned numbers in the order
entered. Should be used if a specific line/panel placement is
desired. If line numbers in a panel are not entered sequen-
tially beginning at 1, they will be renumbered in the order
entered. The volume function requires three lines.
-setting<=value>
Information specific to the various line types:
-setting=|Different| replaces "Display" as the displayed face of
line type -display. Use the pipe (vertical bar) symbol to place
spaces where desired.
-setting=|CDRom| replaces "/cdrom" as the display of -device
type lines.
-setting=f|F or -setting=k|K replaces Celsius with Fahrenheit or
kelvins as the scale for line type -thermal. This effects the
display only, -warning and -critical temperatures must be in
Celsius.
-setting=percent or -setting=% for memory and swap as percent-
age.
-setting=1|5|10|15|30|60 for line type -format uses flite or
another speech synthesizer to cause salmon to announce the time
at the specified interval in minutes. -setting=~label reads an
underscore separated list of times from the personal salmon.cfg
file, -setting=:label reads from the global salmon.cfg or the
-cmdfile=/path/to/file if given. The times must be in 24 hour
format as HH:MM HH:MM etc. Any key or pointer event on the line
toggles the voice on or off.
-setting=HH:MM[ yy/mm/dd] as a second argument for line type
-alarm. Leading zeros are not necessary but both the hour and
minute cells must be filled. The second expiration time is
activated by first stopping the countdown, then enter edit mode
with ESC, up arrow or middle click and finally another up arrow
or middle click to start the countdown.
-setting=[ddd ]HH:MM:SS as a second argument for line type
-timer. Leading zeros are not necessary but the hour, minute
and second cells must be filled. Activate as for line type
-alarm.
-setting=HH:MM for line type -reset sets the reset interval.
Leading zeros are not necessary but both the hour and minute
cells must be filled.
-setting=4 with line=calendar puts salmon into four panel calen-
dar mode.
-setting=pathto/AClineon,pathto/level^full,pathto/level^now from
/sys/class/power supply/ for -powerstate lines when running on
Linux.
-command<=command>
Execute command at timeout or event. When entered at the com-
mand line or read from a configuration file, the shell will
determine where quotes are required. Timers and alarms will
execute -command at timeout, other line types when clicked.
-timer, -alarm or -reset line types will shutdown at timeout if
salmon is SUID and the command is exactly "shutdown". If
-clickoff is set, shutdown will be executed at any button event
on any part of the window. Other than that, any line type can
be used with -command. If a line type is -mount and the argu-
ment is an un/mountable file system and the command is "detach",
any key or button event on the line toggles the mounted state of
the file system. If the mount point is an nfs file system, the
presence of the host on the network will be varified before
u/mount is called. User specified commands other than "detach"
and "shutdown" are not executed SUID.
EXAMPLES
At the command line:
$ salmon -foreground green -magnify=3
$ salmon -execute -execport=49999 -exechost=snarleyow\
-execopts="read :lines &"
With labels in .../etc/salmon.cfg:
:lines
# underscore separated list of option=argument in any order
# line=option option=argument linetype
# backslash line continuation can be used at any point
# goto :label refers to a label in the current config file
# Warning and critical temperaturess are in Celsius.
# The setting= option only changes the displayed temperature.
line=sound=1 thermal=0 warning=40 critical=50 sound1=4 setting=k
line=powerstate warning=30 critical=10 sound=1 sound1=6
line=load1
line=load5
line=load15
thermoff # execute shutdown at > critical temperature
thermtime=1
poweroff # execute shutdown at < critical battery level
powertime=4
goto :theend
:clock
line=linenum=1 panel=1 color=green setting=|Today|is|\
command=salmon read ~lines
line=linenum=2 panel=1 color=green format=|%A|\
setting=~clocktalk
line=linenum=3 panel=1 color=green format=|the|%e--|of|
line=linenum=4 panel=1 color=green format=|%B|
line=linenum=5 panel=1 color=green format=|%Y|
line=linenum=1 panel=2 color=0x87ceff format=|It's|%l:%M:%S|
line=linenum=2 panel=2 color=0x87ceff format=|%p|%Z|
line=linenum=3 panel=2 color=0x87ceff load1
line=linenum=4 panel=2 color=0x87ceff processes
line=linenum=5 panel=2 color=0x87ceff uphours
line=linenum=6 panel=2 powerstate critical=20 warning=40
line=linenum=1 panel=3 color=red alarm sound=23\
command=echo "Please stop that infernal racket."
line=linenum=2 panel=3 color=red alarm sound=24
line=linenum=3 panel=3 color=red reset=12:00\
command=flite -voice slt -t "I'm going out to lunch"
line=linenum=4 panel=3 color=red reset sound=26
line=linenum=5 panel=3 color=red timer sound=11
line=linenum=6 panel=3 color=red timer sound=12
phasecalc # Fills panel 4, color is foreground
pixmap=-13 # Tile background
audiocmd=ogg123 -q
foreground=gold
position=-64-0
appname=Salmon $OS
:clocktalk
# Under score separated list of talking clock times.
# These are not salmon options/arguments.
06:45 07:10 12:01 12:45 15:30 16:15\
18:05 19:32 22:00 00:06
:theend
position=-64+0
foreground=0x87ceff
magnify=4
refresh=1
appname=Salmon 3x $OS
:default
pixmap=-12
goto :theend
FILES
/usr/local/alter/man/man1/salmon.1
/usr/local/alter/etc/salmon.cfg
/usr/local/alter/share/salmon/*.gz
/usr/local/alter/share/salmon/*.au
/usr/local/alter/share/salmon/b*.gz
SEE ALSO
Afterstep documentation
pom(6) sysctl(8) devinfo(8)
strftime(3) strptime(3)
Version 3.0.4 16 May 2015 salmon(1)