

                Features and Options of stic-0.2/bin/simv

This software moves and manages image files in JPEG or GIF format.
Its main purpose is to show the images and to coordinate usual file
management tasks with a picture recognition system.
A list of external helper programs is displayed as appendix to this text.

The program maintains a list of file addresses. A list index points to the
current item which can be manipulated. At start the list is empty. It is
usually filled by the program's arguments but may be extended by dialog
commands as well.

Arguments are commands which get executed before the dialog starts.
Arguments which do not begin with a '-' character get prepended by -addfile:
automatically, so they are added to the list as fileadresses.
At the beginning of the dialog, the first item of the list is made current.

If a file gets moved in or out a directory which contains a file with the
name  .imv_guarded_directory  then the picture recognition system gets
informed about the new address. Therefore all directories which contain
files known to this system should also contain a file .imv_guarded_directory

Files that are in a directory without .imv_guarded_directory  are tested
by the recognition system wether they may already be stored in a guarded
directory. If similar files are found then they are displayed with a second
viewer window.

Many commands which expect arguments like filenames or shell commands
perform parameter substition. This means that before execution certain text
parts get replaced by values known to the program. All these special
text parts begin with a $-sign. The next character decides about the kind
of substitution. See a list what is replaced by what :
 $*       the address of the current item
 $.       main directory (defined by -keyset:maindir)
 $-       trash directory (defined by -keyset:trashdir)
 $~       the user's $HOME directory
 $0       the program's start directory (directory part of argv[0])
 $(text)  perform parameter substitution on text, execute the result as
          shell command and use the standard output of this command.


Commands usually are not toggled in but triggered by shortcut keys or sent
by external frontend programs.
To get a command line prompt, press the '@' key.

If commands come faster than they can be processed, they get buffered and
executed as soon as possible. The ESC key discards all pending commands
and all those keystrokes and commands which follow the ESC immediately.
Please note that a lot of special keys produce sequences with ESC and
therefore cannot be used for key binding up to now.

Commands are bound to single keys by option -keyset which takes a single
keyset statement as parameter.
See below command -keyset and the sample keyset definition.

External frontend programs can connect via TCP/IP or named pipes.
They may send commands and apply for notification of any output event.
See below -pipe_service , -tcp_service, -add_view , -show_copy .
This software itself is able to act as such a frontend program via TCP/IP.
The connection may be encrypted to be secure against malicious clients
or third party interference. See below -security and -tcp_client .

Unencrypted, the input protocol simply consists of command lines separated
by CR+LF, LF or NUL bytes. Several classes of output messages may be
subscribed by -add_view .



                Command reference of application commands

-addfile:fileaddress
     Append the given file address to the list and make it the current item.

-addfile_list:fileaddress
     Read the given file and append all non-empty lines as file addresses to
     the list. The last added item becomes the current one.

-back
     Make the previous list item current.

-doubleto:directoryaddress
     Move the first item of the displayed similar files to the given
     directory. This is mainly used to replace poor versions of an image
     by a new and better one.
     Performs parameter substition.

-for:[+|-]start_index:[+|-]end_index:command
     With each list item beginning with start_index and ending with end_index
     perform the given command. Abort loop on error. If end_index is smaller
     than start_index, then command is not performed at all.
     The current item index is set according to the last run of command
     within the loop.

-jpgb
     Convert the current item to old fashioned JPEG format. A quality
     parameter can be stored in the file .imv_jpgb_quality_value but a
     reasonable value is already preset at program start.
     The original file is preserved within the trash directory so this
     command does not immediately save disk space when reducing file size.

-jump:[+|-]index
     Make the list item current which has the given list index.
     The index may be any number larger than 0. If it is preceded by a '+'
     or '-' then the index is added resp. subtracted from the current index.
     Note: -jump:+1 may cause the program to end if -end_on:list_end is set.

-list:[+|-]start_index:[+|-]end_index[:option]
     List the indice and addresses of the files in the range from
     start_index to end_index.
     An index may be any number larger than 0. If it is preceded by a '+'
     or '-' then the index is added resp. subtracted from the current index.
     If option is "raw" then only the file addresses are listed.
     If option is "count" then also the total number of files is listed.

-mapper_cmd:mapper_command:databaseaddress:glue_character
     Set the shell command, the database and the glue character (e.g. ':')
     for calling the picture recognition system. A call will be formed by
      <mapper_command><glue_character><databaseaddress> \
        <option><glue_character><filename>
     Where option is in {-append, -refresh, -del_file, -search, -lookup_adr}
     This command should be used with great care, if ever. Under normal
     circumstances, -mapper_db  should be sufficient for all purposes.

-mapper_db:databaseaddress
     Set the database to be used by the picture recognition system.

-moveto:directoryaddress
     Move the current item to the given directory.
     Performs parameter substition.

-refresh
     Redisplay the current item and eventually its lookalikes. Also print
     again the file information lines.

-skip
     Make the next list item current.
     Note: -skip may cause the program to end if -end_on:list_end is set.

-undo
     Revoke the most recent operation which altered the content or the
     address of a list item. Currently operations can be undone back
     to the program's start. -undo does not revoke -addfile (i.e it does
     not remove items from the list).

-where:criterion:regular_expression:command
     For all items in the list, test the criterion with the given regular
     expression. If it matches, execute command with that item.
     Criterion may be one of :
       "name" the last part of the current item's address
       "dir"  the other part of the current item's address
       "adr"  complete current item's address
     For a description of regular expressions see: man 1 ed , man 7 regex
     The current item index is set according to the last run of command
     within the loop.


                   Command reference of agent commands

#text or !text
     Remarks. They are ignored like empty commands.

:character
     Same as  -synthetic:-1:1:character  (see below)

-add_view:connection:subscription:representation[:encapsulation]
     Subscribe to a class of output events. This is the way how frontend
     programs get informations. There are several kinds of subscriptions:
       prompt             get notified when the server is idle and when it
                          becomes busy.
       stdout             get texts which are directed to standard output
       stderr             get texts which are directed to standard error
       current_file       get the current file (usually its name)
       double_files       get the list of possibly double files
       current_file_copy  get the copy of the current file (see -show_copy)
       double_files_copy  get the list of copies of possibly double files
       ask                get questions
       mark               get start and end of command -mark.
       reply              get start and end of command -request.
       all                subscribe to all output events
     Any time this program (the server) changes one of the subscribed states
     it sends a notification to the client using the chosen representation.
     The connection parameter may be a filename or a "-" character. A "-"
     tries to use an already established back channel to the frontend
     program. This will fail if the input connection is a pipe and no
     filename was given with a previous -add_view: from that client.
     It is ok to use a connection filename several times from within the
     same frontend program.
     The representation should be "default" up to now.
     If encapsulation is given as "encapsulated" then the view will only
     receive notifications caused by commands from the same input connection
     as this -add_view command. If encapsulation is set to "open" any
     command's output may be received.
     This setting applies to all subscriptions of the same view id (see
     below Appendix B, notification "init").
     There are two subscriptions which are served automatically together
     with any other subscription:
       init           notifies that about the first subscription which is
                      assigned to a backchannel.
       end            notifies that the backchannel will be closed by the
                      server now (e.g. because it ends service).
     Also the subscriptions  mark  and  reply  are served as soon as any
     subscription is made. These notifications emerge from commands -mark
     and -request.
     The format of notification messages is described in appendix B.

-arguments_to_queue
     Only in effect for commands given as program arguments. Usually the
     arguments are interpreted before the input for dialog is started.
     This prevents unwanted outside interaction during setup.
     By -arguments_to_queue all following arguments are placed in the input
     buffer. So they get executed as user commands from internal input as
     soon as dialog service starts.
     For automated start of -tcp_client it is desirable that all following
     arguments are sent to the server rather than waiting for the end of
     client mode. Use:  -arguments_to_queue -tcp_client:... ...

-ask_end
     Ask for Y or N . End program if answer is Y.

-bundle:mode
     After the command  -bundle:start  all following commands from the same
     input channel are buffered and their execution is delayed until the
     command  -bundle:end  or again  -bundle:start  is received.
     The execution of the buffered commands will not be mixed with commands
     from other channels. So one can rely that a combination of -jump and
     -moveto will really move the desired file even if a lot of other
     clients are using the server without any coordination.
     Be aware that the total size of buffered commands per channel is
     limited (but at least 64 KB ).
     -bundle may not be prepended by any other command (e.g. -mark).

-double_check:mode
     In applications which show a current image item, a picture recognition
     check may be performed to find very similar images. This command
     wether such a test shall be performed by appropriate applications.
     Mode "off" disables the check, "on" performs it with any current
     image item. Mode "auto" allows the application to check only those
     images, which are not already under the management of the recognition
     system.

-encapsulate_views:switch
     If switch is set to "on" this command excludes other views from
     being notificated about the effects of commands. Only the internal
     output channels (see -internal) and the views of the command's sender
     will get these notifications. This mode is useful if the clients of this
     program are not aware about each other and would interfere with their
     replies.
     "off" is the normal mode where all subscribers get all subscribed
     notifications.

-end
     End the run of the program.

-end_client
     Ends client mode. This mode eventually was initiated by -tcp_client .

-end_on:trigger[:option]
     Set or delete trigger for automatic end of program. The trigger is
     deleted if option is 'clear' .
     Triggers defined up to now:
        list_end     is true if the current item cannot be set because the
                     end of the file list has been reached.
        prompt       (only effective in client mode) is true if the server
                     indicates to be idle by a 'prompt' notification.
        timeout      is true after the number of seconds given by option
                     has elapsed without a new -end_on:timeout.
        idle         is true after the number of seconds given by option
                     has elapsed without receiving an input event.
     A general trigger is defined which combines all triggers.
        all          is true if any trigger is true.
     Therefore -end_on:all:clear deletes all triggers.

-end_server
     Sends an -end command to the server and ends client mode. This command
     is ignored if the program is not in client mode.

-help[_short]
     Print this text. -help_short only prints the keyset help text.
     The program ends without any dialog if -help is its last argument.

-input_ready_fd:code
     In client mode, this command notifies that data is available from
     the server. In normal (server) mode, this command is ignored.

-internal:channelname:switch
     Enable or disable internal i/o channels. Available channel names are:
       current_file      the internal viewer for current files
       double_files      the internal viewer for possibly double files
       stdout            texts directed to standard output
       stderr            texts directed to standard error
       termios           listen for single character terminal input
       all               all of the above channels
     Switch may be either "on" or "off". Default is "all:on".

-keyset:statement
     Manipulate the keyset mapping from single keystrokes to commands.
     A statement consists of a code word and possibly additional text.
     See also the example keyset definition below.
     Keyset statements:
       clearall             Clears the whole keyset.
       clear:keys@          Clears the mappings for one or more keys.
       clear:#code@         Clears the mapping for a key by its decimal code.
       helpstart:text       Clears the short helptext and adds first line.
       helpmore:text        Adds another line to short help text.
       maindir:address      Sets a common parent directory for file
                            addresses with 'map' and 'trashdir' which do not
                            begin with '/'.
                            Performs parameter substition.
       map:keys@command     Maps one or more single keys to a single command.
                            Use the same commands as for the command line but
                            no remarks.
       map:@#code@command   Maps a key by its decimal ASCII code to command.
       readfrom:filename    Reads keyset statements from a file one statement
                            per line. See example below.
                            Performs parameter substition.
       trashdir:address     Sets the directory which keeps old file versions
                            for the -undo command.
                            Performs parameter substition.
       #text or !text       Remarks. They are ignored like empty statements.
     '@' (ASCII 64) and ESC (ASCII 27) cannot be mapped at all.
     If a key gets more than one mapping, then all these commands get
     executed in the same sequence as they have been mapped to the key.
     So if a key is to be newly defined, "clear:" should be applied first.
     Mapping for multi character keys (like F1) is not possible yet.
     Leading blanks before the code word (e.g. 'map') are ignored.
     Blanks between @ and 'command' are ignored. All other characters up to
     the line end are significant.

-make_userkey:connectiontype:username
     Convert a file into an encrypted keyfile suitable for secure
     connections. The connectiontype may be one of:
       "tcp","file","internal","all" .
     It is used to determine the keydirectory which may be set by -security.
     Within the keydirectory there has to be a file {username}.tnl with at
     least 64 bytes of content. The first 64 bytes are condensed and
     encrypted into a 16 byte key which replaces the original file content.
     Permission to read or write the file is granted only to the owner.

-mark:id:command
     Notify the sender about start of command, execute command and notify
     about the end directly before the program checks for the next command.
     Other clients will not see the mark notifications.
     Note: the command -bundle will not work as argument of -mark.

-permission:username:class[-action]:["permit"|"deny"]
     Set a rule to permit or deny execution of particular actions by
     particular users. As soon as the dialog mode starts, the rules are
     checked with the effective username whenever a command requests a
     program action. Be careful with this command in dialog mode since you
     might exclude yourself from entering the next rule.
     The effective username is obtained from the authentication of the
     command's input connection. If no authentication by encryption has
     been enabled at that connection, the username is "external_anonymous"
     for external programs and "internal_owner" for program arguments
     and input at stdin.
     Username "all" in a rule applies to any effective user.
     Any action belongs to a class (like "shell" or "move") but may
     also be addressed individually. The youngest matching rule applies.
     Example (deny shell commands for any user other than "internal_owner"
              but allow the use of a particular script with current item):
       -permission:all:shell:deny
       -permission:internal_owner:shell:permit
       -permission:all:shell-/home/scripts/infoscript $*:permit
     For a complete list of classes, see appendix agent P below

-pipe_service:type:filename
     Create filename as named pipe and listen for input. The parameter type
     determines how the input shall be used :
       1= handle single bytes as keystrokes.
       2= handle text lines as commands.
       3= send text lines to stdout
       4= send text lines to stderr
     For frontend programs only type 2 is useful. Type 1 is discouraged.
     If filename already exists and is a regular file, it gets replaced by
     the named pipe. The named pipe is removed when it is closed.
     Usually the first action of a frontend program is to send a -add_view
     command with the name of the pipe for output.

-queue_canceled
     In client mode this causes a ESC line to be sent to the server.
     In normal (server) mode, this command is ignored.

-readfrom:fileaddress
     Read lines from file and execute each one as command.
     Performs parameter substition.

-repair_icv:statement
     Set or delete trigger for automatic conversion which cause the internal
     current view process to exit with nonzero value. This happens mostly if
     the format of the imagefile is not known to the viewer program.
     There are two possible statements:
        on .... if the viewer exits badly, try to repair the file via -jpgb
        off ... do not try to repair the file

-request:id:command
     Notify the sender about start of command, execute command and notify
     about the end directly after the command itself ended. Text messages to
     standard output will only be delivered to the sender of -request.
     Other clients will not see the mark notifications. This is similar
     to -mark but the end notification will be sent more early.
     Note: the command -bundle will not work as argument of -request.

-shell:shellcommand
     Execute a shell command.
     Performs parameter substition if the application supports it.

-security:connectiontype:option:value
     Add an access rule to the security list for remote connections.
     The connectiontype may be one of: "tcp","file","internal","all"
     Options may be:
       tunnel        controls encryption. Possible values are "require"
                     "allow" or "refuse" encryption.
       user          its value sets the username for encryption.
       keydirectory  its value sets the directory with the user key files.
       controller    controls access to the -security command. Initially
                     only "internal" connections (i.e arguments and
                     keyboard) are allowed to use this command.
                     By value "on" one may enable other connectiontypes
                     which then should have set "tunnel:require".
     If more than one rule matches, the youngest one is used.

-show_copy:connection:subscription:options:target
     Subscribe to a copy-and-notification service for image files. Different
     from -add_view this subscription makes a copy of the files to be shown.
     Then it notifies its subscriber about the addresses of the copies.
     Any other subscribers of "${subscription}_copy" will get notified
     only if connection is "*". In this case -show_copy has no own back
     channel but relies on channels which have to be subscribed by -add_view.
     Other connection names are handled like in -add_view.
     Subscription may be one of :
       current_file       copy the current file
       double_files       copy the possibly double files
       all                all of the above
     Options may be a list of the following keywords and their eventual
     parameters:
      max_number=number  limits the number of copied files. This may be
                         be necessary for subscription "double_files".
      encapsulate        if this keyword is present, subscriptions are
                         encapsulated (see -add_view). Also the display of
                         copyfiles does end not before the next command from
                         the same input connection is received. Without this
                         keyword copyfiles end display as soon as the next
                         file is to be displayed.
      keep=seconds       copyfiles normally get removed when the subscribers
                         are notified about end of their display. They may
                         be kept available on the disk for the given number
                         of seconds. This is useful if serving for a web
                         server whose clients may need some time to load
                         the files.
     Target is a file address template. For an particular file it will be 
     extended by a unique counting number and the file name's dot extension.
     Example: target=/tmp/simv_current  , filename=/home/me/my_cat.jpg
              Name of copy:  /tmp/simv_current_1168105077.jpg
              This name is sent with a "current_file_copy" notification.
     Despite copyfiles get removed if all goes well, one should use a
     separate directory which is easy to clean from old remnant file copies.
     Just in case that something goes wrong.

-synthetic:connection:type:text
     Create a synthetic input event. Useful to emulate a keystroke
     via a line oriented input connection. The value of "connection" has
     to be -1 up to now. "type" tells how to handle "text" :
         1=keystroke , 2=command line , 3 = to stdout, 4 = to stderr

-tcp_client:hostname:portnumber[:representation:[encapsulation]]
     Enter client mode. This means to connect to a peer program and to
     subscribe for all output events. Most of the input events will be
     forwarded to the peer and the incoming notifications will be
     printed and sent to the own frontend clients. The internal image
     viewers for current and double files are disabled though.
     The peer has to provide TCP/IP service by -tcp_service:hostname:...
     Commands that are handled locally:
        -add_view , -end , -end_client , -input_ready_fd , -internal
        -queue_canceled , -show_copy , -tcp_service
     If a username has been set by  -security:tcp:user:...  then
     this name is used for for authentication and encryption.
     (see appendix C)
     If representation is "data" then the subscriptions for image files
     will cause the server to transmit the whole file contents together
     with their addresses. All subscriptions made by -show_copy at this
     client will make their file copy from the transmitted content rather
     than trying to read the file itself. If internal file viewers are
     enabled (by -internal after -tcp_client), then they show these file
     copies rather than trying to read the file itself.
     This notification method is helpful if direct file access is not
     possible due to access restrictions or due to incompatible file
     addressing (try: -show_copy:... -tcp_client:... -internal:all:on ).
     If encapsulation is given as "encapsulated" then the client will
     only receive notifications which are caused by its own commands.
     If encapsulation is "open" or missing, any command's results may
     be received.

-tcp_service:type:hostname:portnumber:access_mask[:option]
     Offer service for frontend programs via TCP/IP. A client like telnet
     or a peer of this program itself (see -tcp_client) may connect to
     the address given by hostname and portnumber. Depending on the given
     type, input will be handeled differently:
       1= handle single bytes as keystrokes.
       2= handle text lines as commands.
       3= send text lines to stdout
       4= send text lines to stderr
     For frontend programs only type 2 is useful. Type 1 is discouraged.
     If portnumber is 0, the operating system will assign one automatically.
     The access_mask describes (in hex) which hosts other than localhost
     are allowed to connect. Connection is refused if :
       ( access_mask & foreign_address ) != ( access_mask & host_address )
     Where host_address is the address of hostname given with -tcp_service.
     Please note that this might be circumvented by IP-spoofing and that
     there is no check of user identity. Nevertheless the mask test provides
     a first defense against denial-of-service attacks.
     In hostile IT environments, use -security:tcp:tunnel:require  to demand
     user authentication and encrypted communication. See also appendix C .
     Examples: Serve at port 50000, do only accept connections from localhost
       -tcp_service:2:localhost:50000:FFFFFFFF
     Accept connections from own C-class net (assuming own hostname = ts4)
       -tcp_service:2:ts4:50000:FFFFFF00
     Accept from anywhere
       -tcp_service:2:localhost:50000:00000000
     If 'option' is given as "obstinate" the program will ignore errors
     with call bind() and try to obtain a server socket until it finally
     succeeds (or the program gets stopped).

-user:username:command
     Require permission to execute command not only for the authenticated
     user but also for the one given by username.

-viewer_cmd:shellcommand
     Set the shell command which starts an image viewing program. The program
     will be started to display one or more image files.
       ${shellcomand} -geometry [+|-]0+0 ${filename_1} ... ${filename_N}
     A geometry of +0+0 should create the image window at the upper left
     of the screen. -0+0 should do the same adjusted to the upper right.
     Tested shellcommands on Linux : xv , display


                      Appendix agent A :  Keyset Definitions

Usually a keyset definition is written to a file and read by -keyset:readfrom
There are only few sagent commands which make sense with keys, so better look
at Appendix application A for a more realistic example.

If the content of file /home/me/sagentkeys looks like that:

  # Clear old keyset
    clearall

  # Some helptext
    help: -disable_text  +enable_text  ?help  Quit
  # disable output of text
    map:-@     -internal:stdout:off
    map:-@     -internal:stderr:off
  # enable output of text
    map:+@     -internal:stdout:on
    map:+@     -internal:stderr:on
  # The help key
    map:?@     -help_short
  # Ask wether the program shall end
    map:Qq@    -ask_end

then the command
  -keyset:readfrom:/home/me/sagentkeys
activates this definition and overwrites the old one.


              Appendix agent B : Format of Notification Messages

A notification is a message consisting of a header and some fields.
It is terminated by a linefeed although it may contain 8-bit data.
  subscription number_of_fields [field[...field]]\n
A field consists of its (printable) header and a 8-bit data part :
  :name:representation:number_of_bytes:bytes
Example:
  current_file 2 :idx:data:1:5:file1:address:20:/usr/pictures/me.jpg\n
                 |first field||---------- second field ------------|

Message format of particular subscription notifications.
{#} is the number_of_bytes in decimal.
For better readability, each field is shown in a separate line.

When the server encounters the first subscription of a client :
  init 1 :id:data:{#}:{id-number}\n
This message is also generated by every single -show_copy subscription.
When the server ends service, for every "init" it issues an "end" :
  end 1 :id:data:{#}:{id-number}\n

Message to standard output resp. standard error :
  stdout 1 :text:data:{#}:{text}\n
  stderr 1 :text:data:{#}:{text}\n

When a file is added to the list
  list_change 3 :idx:data:{#}:{index}
                :action:data:6:append:
                :item:data:{#}:{filename}\n
When the filename of a list item changes, "action" is set to "change"
  list_change 3 :idx:data:{#}:{index}
                :action:data:6:change:
                :item:data:{#}:{filename}\n

When the current file gets displayed by the internal viewer :
  current_file 2 :idx:data:{#}:{index}
                 :file1:address:{#}:{filename}\n
or if subscribed with representation "data" :
  current_file 3 :idx:data:{#}:{index}
                 :file1:address:{#}:{filename}
                 :content1:data:{#}:{filecontent}\n
When the current file ends to be displayed :
  current_file 0 \n
If two possibly similar images were found by the recognition system :
  double_files 2 :file1:address:{#}:{name1}
                 :file2:address:{#}:{name2}\n
or (if subscribed by representation "data")
  double_files 4 :file1:address:{#}:{name1}
                 :content1:data:{#}:{content1}
                 :file2:address:{#}:{name2}
                 :content2:data:{#}:{content2}\n
When the display of these similar images ends :
  double_files 0 \n
The same formats are used for subscriptions "current_file_copy" and
"double_files_copy" (see -show_copy).

When the server becomes idle :
  prompt 2 :idx:data:{#}:{index}
           :count:data:{#}:{total_files}\n
When it gets busy :
  prompt 0 \n

When a question is asked :
  ask 4 :id:data:{#}:{question_id}
        :type:data:{#}:{type}
        :text:data:{#}:{question_text}
        :constraint:data:{#}:{rules}\n
When the question has been answered :
  ask 4 :id:data:{#}:{question_id}
        :type:data:6:cancel
        :text:data:0:
        :constraint:data:0:\n

Output is done by the particular commands as well as by the command loop
which informs about the command before and possibly about the current item
after execution. The command -request surroundis exactly the command's
output and does not include any loop output. The command -mark surrounds
everything after "prompt 0" up to and including "prompt 2 ...".

Before a command given with -mark is executed:
  mark 2 :state:data:5:start
         :id:data:{#}:{id given with -mark}\n
Before the program checks for the next input event after -mark
  mark 2 :state:data:3:end
         :id:data:{#}:{id given with -mark}\n

Before a command given with -request is executed:
  reply 2 :state:data:5:start
          :id:data:{#}:{id given with -request}\n
After the command has been executed:
  reply 2 :state:data:3:end
          :id:data:{#}:{id given with -request}\n

One can explore the notifications by telnet. Connect to the server
(enabled by -tcp_service) and send:  -add_view:-:all:default
Then operate the server via its usual interface and watch the messages
received by telnet. One also may send command lines from telnet.


             Appendix agent C : Authentication and Encryption

Connections between the program and its frontends may be made secure by
a user-related 128-bit encryption key. A user's key is stored in a file
within a keydirectory which is known to the program. The file's name is the
user's name extended by .tnl . Anybody who is able to read that file is
authorized to connect under that user identity. Therefore, restrictive
access permissions should be set for that file.

By help of command -security one can set the keydirectory, the security
requirements of a server and the username for use with -tcp_client.
The particular connection types may have separate settings.

The content of a user's keyfile is encrypted by the internal key of the
program. Since this key may vary from installation to installation, it
is better to use -make_userkey rather than creating the keyfile by other
means. Create an original 64-byte file of random bytes, transport it and
convert it locally.

If a user's keyfile has been installed at both hosts, it is sufficient to
allow encryption at the server side and to set a user for type "tcp" on
the client side. When client mode starts (by -tcp_client) the necessary
handshake is performed automatically between server and client.

Default security settings are :
   -security:all:tunnel:refuse
   -security:all:controller:off
   -security:tcp:tunnel:allow
   -security:internal:controller:on
   -security:all:keydirectory:${HOME}/tnl_dir
Remember: the youngest matching rule wins. So encryption is only allowed for
TCP/IP connections and security controlling is only allowed for internal
input (program arguments and termios/stdin at the start terminal).
So usually one only has to set a username before connecting to the server.
   -security:all:user:{username}
   -tcp_client:{hostname}:{portnumber}


               Appendix agent L : Legal stuff

This software is copyright 2001, Thomas Schmitt stic-source@gmx.net and
provided to you without any warranty under an open source BSD license.
(see file COPYING)


                Appendix agent P : Permission Classes

Any action caused by a command is checked against rules which may have been
defined by the command -permission . A rule may address a whole class or a
single action. Depending on the command, more than one action may take place.
The application command
   -moveto:$(/home/scripts/find_target $*)
first tests for
   class="move"  , action="moveto"
and then for
   class="shell" , action="/home/scripts/find_target $*"
Nearly all commands test for their class and name, but -shell execution tests
for class "shell" and the shell command before parameter substition takes
place. The command -user tests for class "user" and the given username.

  Class       Command (resp. Action)
------------------------------------------------------------------------
  security    -security , -make_userkey , -permission, -viewer_cmd
  shell       -{shell command before parameter substitution}
  end         -ask_end , -end , -end_client , -end_on , -end_server

  service     -encapsulate_views , -pipe_service , -internal , -keyset
              -show_copy , -tcp_client , -tcp_service

  cancel      -queue_canceled

  user        -(username given with command -user)
  client      -add_view , -bundle , -mark , -request , -synthetic
  script      -readfrom
  help        -help

For application specific commands, see the appropriate appendix P.

Special care should be taken for class "shell". If permitted, the commands
are executed under the user id which started this program. Class "security"
should be even more restricted to avoid unauthorized changes of permissions.

Note that  -permission:all:security:deny  is quite final in dialog. You
will get no chance to enter further -permission commands. So, only if given
in the program's start arguments, a set of rules may begin like that :
 -permission:all:security:deny \
 -permission:all:shell:deny \
Control terminal and program arguments get administrator permissions :
 -permission:internal_owner:security:permit \
 -permission:internal_owner:shell:permit \

Others are allowed to perform some selected shell commands :
 -permission:all:shell-/home/scripts/infoscript $*:permit
 -permission:all:shell-/home/scripts/automatic_move_target $*:permit

For a quite mistrusted user "webserver" one may additionally define :
 -permission:webserver:all:deny
 -permission:webserver:client:permit
 -permission:webserver:navigation:permit
 -permission:webserver:help:permit
 -permission:webserver:info:permit
from class "modify" we only allow action -repair_icv:
 -permission:webserver:modify-repair_icv:permit



                      Appendix application A :  Keyset Definitions

Usually a keyset definition is written to a file and read by -keyset:readfrom
If the content of file /home/simv/anikeys looks like that:

  # Clear old keyset, set main directory and trashdirectory
    clearall
    maindir:/home/pictures
    trashdir:$./removed_pictures

  # Define three move targets with capital and small letters
    helpstart:Mice Horses Cats             (caps reform file before moving)
  # Map the capital letters MHC to a conversion to standard format
  # (they get extended below so they finally perform -jpgb before -moveto.)
    map:MHC@   -jpgb
  # Map the keys 'M' or 'm' to : -moveto /home/pictures/mice
    map:Mm@    -moveto:$./mice
  # Map the keys 'H' or 'h' to : -moveto /home/pictures/horses
    map:Hh@    -moveto:$./horses
  # Map the keys 'C' or 'c' to : -moveto /home/pictures/cats
    map:Cc@    -moveto:$./cats


  # Some general keys not specific to the file management task
    helpmore: >forward <backward -delete ~deldouble &undo !reform
  # The help key
    map:?@     -help_short
  # Navigation keys : '>' and SPACE move forward
    map:> @    -skip
  # Navigation keys : '<' and BACKSPACE move backward
    map:<@     -back
    map:@#127@ -back
  # Deletion keys for current item and its first lookalike
    map:-@     -moveto:$./removed_pictures
    map:~@     -doubleto:$./removed_pictures
  # Undo and file format normalizer
    map:&@     -undo
    map:!@     -jpgb

then the command
  -keyset:readfrom:/home/simv/anikeys
activates this definition and overwrites the old one. It does not matter
wether given as argument, in dialog or read from a file.


              Appendix application L : Legal stuff

This software is copyright 2001, Thomas Schmitt stic-source@gmx.net and
provided to you without any warranty under an open source BSD license.
(see file COPYING)


              Appendix application P : Permission Classes

This is a list of application permission classes and their commands.
see "Appendix agent P" for more information about permission classes.

  Class       Command (resp. Action)
------------------------------------------------------------------------

  security    -mapper_cmd

  service     -mapper_db

  modify      -repair_icv , -jpgb
  move        -doubleto , -moveto
  filelist    -addfile
  undo        -undo

  navigation  -back , -skip, -jump
  info        -list, -refresh
  loop        -for , -where

------------------------------------------------------------------------


----------------------------- External helper programs ------------------------

Image conversion program   :  convert -comment '' -quality 80
Picture recognition system :  similar -mapname:
Image viewer               :  display
Textual file information   :  ls -l

-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
 ?help >forward <backward =isknown -delete ~deldouble &undo !reform
-------------------------------------------------------------------------------
