KIT(1) KIT(1)
Version 2.0 PL28
NAME
kit, mailkit, unkit - the ultimate mailing tools
SYNOPSIS
kit [ -EFHMBVXefhpx ] [ -S size ] [ -a address ] [ -k key ] [ -d dir ]
[ -m address ] [ -n basename ] [ -l file ] [ -s name ] directories |
files
mailkit [ -EFVcefhp ] [ -l file ] [ -n partname ] title [ address(es) ]
unkit [ -bhlprsSV ] [-d dir ] [ -k key ] [ files ]
DESCRIPTION
Kit is the ultimate mailing tool. It enables you to mail data without
any consideration of possible escape sequences or control characters.
Given a file name or a directory, it builds a single file using tar(1)
and compress(1). Then this file is hex-encoded (option -H) or ASCII-
encoded with btoa(1) (option -B, which is used by default) before
being shell-archived. Kit produces files that match "Kit*" regular
expression. This default base name can be changed thanks to the -n
option. With the -m option, it is possible to give one mail address,
and kit will invoke mailkit to send the archive. There may be as many
-m options as needed (to send the same archive to more than a single
person). If there are a lot of recipients, you may want to store them
in a file and use the -l option to tell kit where the recipient file
is located.
The -E, -F, -e, -f and -p options are passed on to mailkit, so if no
-m option is used, they will be ignored. When sending files with -m,
the subject of the message holds the name of the first file given in
the command line (supposed to be the name of the kit). It is possible
to overwrite this default by using the -s option.
If you want to send sensible data, it is possible to encrypt them
using a public-domain implementation of Data Encryption Standard
(DES). The -x option will use the Cipher Block Chaining mode
(default), while -X requests the Electronic Code Book mode. If you do
not specify the encryption key with -k, des(1) will prompt you for
one. If you use the -k option, -x is assumed.
It may happen that there are no write permissions in the directory
where the root directory to be kitted lies. The -d option enables you
to specify another directory, where all the temporary files will be
stored. If you use something like /tmp, you must be careful to use -n
to change the base name used (in case someone else is doing the same
thing, otherwise files may get mangled). To prevent common mistakes,
kit will stop and give an error message if the argument of -d is not a
directory, if the directory is not writable by the user, or if a kit
file is present in the temporary directory (same base name).
- 1 - Formatted: April 20, 2024
KIT(1) KIT(1)
Version 2.0 PL28
When you send a kit to someone who may not have kit, the -M option may
be used to include a minikit script, which is a minimal set of
commands to unkit an unencrypted ASCII-encoded kit. The overhead is
small (around 4K) and some instructions are provided in the header of
every kit part. The minikit is usually called minikit, but should you
already have a file with that name in your distribution, it will be
renamed MINIKIT. If by chance (!) you named one of your files MINIKIT,
then a unique name of the form mkitXXXXX will be generated (XXXXX
stands for the PID of the kit process).
By using the -a option, you ask the remote unkit program to send an
automatic acknowledgment to the specified e-mail address upon
successful archive extraction. However, this feature is only supported
if the remote end has at least the 2.0 PL15 release. You will receive
a short message with a junk precedence, telling you who extracted the
archive and when.
The default part size generated by kit is currently 50000 bytes.
However, this can be changed throughout the -S option, which expects a
part size as argument. It can be given in bytes (e.g. -S 40000 to set
the maximum part size to 40000 bytes) or in kbytes by appending a k at
the end (i.e. -S 60k would produce parts with size ranging up to 61440
bytes).
Mailkit takes "Kit*" files and sends them to a list of addresses. The
-n option can be used to change that base name, if necessary. Each
message sent corresponds to one part and has its `Subject:' field set
to the number of this part with the title given, and you also have the
total number of parts, so that missing parts can easily be located.
The options -E and -e from mailkit enable you to give the recipient
some instructions. They both call an editor. At the top of the file
edited, there is a little message, which will (of course) be stripped
from the text you enter, so do not remove it or your own message will
be cut instead. With -E, the message will be sent in an extra part
(#0), while with -e it will be included in each part. Empty messages
will be ignored.
Options -F and -f are very similar, but take their input from stdin
(standard input) instead of calling an editor. Option -p asks mailkit
for preserving mailed files. They are removed by default.
When mailkit is given a -l option, it takes the file name as a file
whith recipients addresses in it and adds the optional addresses that
may be given on the command line. Addresses in the recipient file are
separated with spaces, commas or new lines. Shell-style comments
starting with a pound sign (#) are allowed. More than one -l can be
used to get addresses from multiple files (duplicates will not be
removed by mailkit but should be taken care of by the underlying
transport mechanism).
- 2 - Formatted: April 20, 2024
KIT(1) KIT(1)
Version 2.0 PL28
If mailkit is invoked by kit via -m options, it will be given the -c
flag to clean up parts when they are successfully sent, unless -p was
also provided. However, when invoking mailkit directly from a shell,
the default action is to not remove the parts when they have been sent
(that is to say, -p is the default action unless you add the -c option
yourself). If for some reason one part could not be sent and mailkit
was directed to remove parts when sent, then the file is not removed
immediately. If the input and output are connected to a terminal,
mailkit will ask you at the end whether you wish to keep the unsent
parts, on an individual basis. Otherwise, (e.g. standard output
redirected to a file), the unsent parts will be removed without
asking.
Another useful feature when invoking mailkit manually is the ability
to send only a subset of all the kit parts by using the -r option and
supplying a range list of parts to be sent. A range list is a set of
ranges comma separated. A range is a part number by itself or a set of
two numbers separated with a minus sign, indicating the lowest and the
largest bound, hence specifying an interval. If the lowest bound is
missing, 1 is assumed. If the largest bound is missing, the total
number of parts is substituted. Thus, a range of 1- means all the
parts, while 1,4-7,10 would send parts 1, 4 trough 7 and 10. Finally,
-5,8- would send parts 1 through 5 and 8 up to the end. If you
introduce spaces in your range list specification, do not forget to
quote the whole list for the shell...
Unkit is used to restore the original files. The argument is a list of
archive files (or mail files, as unshar(1), which is called by unkit,
can deal with mail headers). Input files are not removed unless
option -r is given. By default, option -p is used to preserve the
input file(s). If no file name is given to unkit, the standard input
is processed. This is useful to process messages directly from a mail
user agent.
You may save more than one kit part into a file and give that file as
an argument to unkit, which will then identify and extract the embeded
parts to process them. The program lists on the standard error the
files as they are processed and tells you how many kit parts it found
within each file.
Sometimes, tar does not work well accross NFS and will fail restoring
ownership on files, even with the -o option. If you chose to install
badtar at configuration time, you may use -b to instruct unkit using
badtar as a filter before running tar. This is the default action on
some systems (the -h option will tell you what was determined at
configuration time).
If you want to know what unkit will create without actually doing it,
use the -l option. With this option, -r is ignored. You may also use
unkit in place of unshar: it will stop after having unpacked the shell
archives if it does not detect any kit file.
- 3 - Formatted: April 20, 2024
KIT(1) KIT(1)
Version 2.0 PL28
When unpacking crypted archives, the -k option may be used to specify
the key to be used by DES. If you do not supply it, DES will prompt
you on the terminal.
By default, unkit will perform security checks on the shell archives
(if perl is available) to detect alien code. It will skip those parts
containing suspicious code which should not be part of the archive.
You may explicitely skip those checks by using the -s option, which
should be used only when unkit input can be reliably trusted.
Unfortunately, the script used to make those checks is written in
perl, so nothing will happen if perl is not in your PATH. The -S
option will make kit abort with an error if it is unable to perform
security checks due to the absence of perl.
For all of these commands, option -V prints the version number with
the current patch level and exits, while -h gives a little help
message with the syntax and the meaning of the options.
OPTIONS
This section summarizes the different options. All the options may be
specified separately (e.g. -a -b foo -c) or grouped together, along
with optional arguments (e.g. -ac -bfoo). Option parsing stops when --
is encountered.
Kit has the following options:
-B Use btoa encoding (default), as opposed to hexadecimal
encoding.
-E Edit instructions which will be sent as part #0.
-F Get instructions to be sent as part #0 from standard
input.
-H Use hexadecimal encoding, as opposed to the default
btoa. This is an obsolete feature, kept for
compatibility with kit 1.0.
-M Include minikit in the distribution, in order to allow
unkiting by the recipient, should kit be missing at the
remote site. Note that minikit will only be able to
unkit plain btoa-encoded packages (i.e. encryption is
not supported, although automatic acknowledgment is).
-V Print version number and patchlevel.
-S size Set each part size in bytes or kbytes (by appending a
single k after the size figure). The actual size of
each part may be slightly bigger than the maximum
stated (a few hundred bytes at most).
- 4 - Formatted: April 20, 2024
KIT(1) KIT(1)
Version 2.0 PL28
-X Encryption with DES Electronic Code Block algorithm.
You will be prompted for a key, unless you specify one
on the command line via the -k option.
-a address Ask the unkiting process to send an acknowldgment to
the specified e-mail address upon successful
extraction.
-d dir Put temporary files in the specified directory. This is
useful if you do not have writing permission in the
current directory. If you specify a common directory
like /tmp, be sure to use the -n option or your kit
might be clobbered if somebody else is doing the same
thing.
-e Edit instructions to be sent at the top of each part.
-f Get instructions to be sent at the top of each part
from standard input.
-h Print usage and option summary.
-k key Set the key to be used for encryption. The -x option
will be assumed, unless -X is explicitely given to
override the default.
-m address Invoke mailkit to send all the parts at the given
address. Several -m may be specifed to send the package
to more than one recipient. The kit parts will be
removed at the end, unless -p is given. When sending
large files to multiple recipients, it is wise to use
this option in case one part gets lost.
-l file Send the kit parts to the recipients held in the file
(one recipient per line).
-n basename Set the basename of the generated parts. The default is
Kit. You should use this option when a kit is already
present in the current directory, or when you use
something like -d /tmp.
-p Preserve file sent. This option is meaningful only when
-m or -l is given.
-s name Set the kit name, which will be copied as-is into the
Subject of messages sent by mailkit (provided -m or -l
is specified), and also in the automatic
acknowledgment. By default, the name of the first
directory or file specified on the command line will be
used.
- 5 - Formatted: April 20, 2024
KIT(1) KIT(1)
Version 2.0 PL28
-x Use DES Cipher Block Chaining encryption algorithm.
You will be prompted for a key, unless you specify one
on the command line via the -k option.
Mailkit recognizes the following options:
-E Edit instructions which will be sent as part #0.
-F Get instructions to be sent as part #0 from standard
input.
-V Print version number and patchlevel.
-c Clean up after each part sent: all the parts
successfully sent will be removed from the disk.
-e Edit instructions to be sent at the top of each part.
-f Get instructions to be sent at the top of each part
from standard input.
-h Print usage and option summary.
-l file Get the recipient list from a file (one recipient per
line).
-n basename Set the basename of the generated parts. The default is
Kit. You should use this option when more than one kit
is present in the current directory, or when you used
the kit's -n option to change the default basename.
-p Preserve files sent. This is the default, unless -c is
specified.
-r range Specify which parts are to be sent. For instance, -r
1,4-7 would send part #1 and then parts #4 through #7.
Unkit uses the following options:
-S Complain loudly and abort if perl is not found, since
that would make it impossible to check each kit part
for possible alien code before running them through the
shell.
-V Print version number and patchlevel.
-b Force usage of badtar.
-d dir Go to dir before starting extraction.
- 6 - Formatted: April 20, 2024
KIT(1) KIT(1)
Version 2.0 PL28
-h Print usage and option summary.
-k key Set the key to be used for data decryption. Unkit is
able to determine automatically whether decryption is
needed or not and will prompt you for the key unless
this option is used.
-l Lists the files contained in the kit package without
extracting them.
-r Remove input files if unshar succeeds.
-s Force skipping of security checks, which are conducted
only if perl is available in your PATH.
FILES
{zag,zcb,zec}.hex.*
temporary files used by kit and unkit for datas which
are hex-encoded.
{zag,zcb,zec}.ba.*
temporary files used by kit and unkit for datas which
are ASCII-encoded.
Kit* files generated by kit
zag* non encrypted temporary files.
zcb* data encrypted using CBC mode.
zec* data encrypted using ECB mode.
zzz.minikit file holding the name of the extras files added by kit.
zzz.ack contains the address where acknowledgment should be
sent.
zzz.subject contains the name of kit archive for acknowledgment
purposes.
/opt/kit/lib/minikit
the script which may be used to unkit a distribution
when the kit package is not available.
/opt/kit/lib/makeshar
the script which emulates cshar's makekit program.
/opt/kit/lib/rshar
a simple shell archive maker.
/opt/kit/lib/secure
security checks (detection of alien code) in kit
archives.
ENVIRONMENT
The following environment variables are paid attention to by mailkit.
If they are not set, a default determined at configuration time will
be used:
EDITOR the name of the editor to call when -E option and
friends are used.
- 7 - Formatted: April 20, 2024
KIT(1) KIT(1)
Version 2.0 PL28
MAILER the name of the program to invoke to send mail. This
program must be ready to take a list of addresses as
argument and the whole message (with some headers
already computed) from standard input.
NOTES
Kit may now be used as a standalone package, i.e. without the help of
the cshar distribution. This was not true before version 2.0 PL10.
Two simple shell scripts now emulate cshar's behaviour. Those scripts
are held in the private library directory because they are not
intended to be used directly by any user.
In order to use kit, hexdecode, hexencode, atob and btoa must be
installed and compress must be available. If any of these is missing,
this mailing kit is useless.
Unkit has its own unshar built-in, but it will not be used if unshar
is installed, because it is really simple-minded and not smart at all
in case of errors. However, this is useful if you do not have cshar,
but still want to use unkit.
EXAMPLES
To mail ram@educ.emse.fr a directory called XLOCK and all what it may
hold, do:
kit XLOCK
mailkit XLOCK ram@educ.emse.fr
Kit will produce files Kit*, and mailkit will send them. Or, to do it
all in one:
kit -m ram@educ.emse.fr XLOCK
Assuming the XLOCK package has 5 kit parts, you could send only parts
3 and 5 by using:
mailkit -r 3,5 XLOCK ram@eiffel.com
If you have no write permissions in the current directory, you can
specify an alternate directory for temporary files:
kit -m ram@eiffel.com -d /tmp -n mykit XLOCK
To unkit, save the mail messages in files called, e.g. xlock.01 (for
part 01), xlock.02 (for part 02) and so on. Then do:
unkit xlock*
Even if it succeeds, files xlock* will not be removed.
- 8 - Formatted: April 20, 2024
KIT(1) KIT(1)
Version 2.0 PL28
BUGS
Try "kit .": it is harmless (well, I hope !), and you will quickly
understand the problem. The solution is to use the -d option.
If you use the -r option in unkit and one or more kit parts are
missing, all the files will be lost. So use it with care...
Some systems cannot extract tar archives with overwriting of ownership
informations (usually this is done with tar option -o).
The -M option is unknown to versions of kit prior to 2.0 PL9, which
means the remote unkit program will not be able to clean-up the extras
files. Similarly, the automatic acknowledgment feature was added at
2.0 PL15. Fortunately, kit programs newer than 2.0 PL9 will know how
to deal with the extras files, although the acknowledgment feature
itself will only be handled by 2.0 PL15 and later versions.
SEE ALSO
atob(1), btoa(1), unshar(1), makekit(1).
AUTHOR
Raphael Manfredi <ram@acri.fr>.
Kit was first developed at the Ecole des Mines, Saint-Etienne, France.
Many improvements were added at Interactive Software Engineering Inc.,
Santa-Barbara CA, USA.
- 9 - Formatted: April 20, 2024
