tazinst frontend protocol
=========================

Frontends (dialog TUI, tazpanel CGI, GTK GUI) drive the tazinst
backend through its command line. This file is the contract: records
may gain fields at the end, fields are never reordered or removed.

Records
-------

One record per line, fields separated by a TAB. A field never holds a
TAB or a newline, but it may be empty. In shell, split records with
awk -F'\t' or cut -f: 'read' with IFS set to a TAB merges empty fields,
because a TAB is IFS white space.

The install file defaults to ./tazinst.rc, every command takes another
one as its last argument.

Settings
--------

  tazinst describe [file]

One record per setting to ask for, in order, for the current mode:

  key  type  required  active  value  label  help  warning

  type      choice, partition, file, text, password, bool or none
  required  1 if the value can not be empty
  active    0 if the setting does not apply with the current values
            (source with a CD, home_format without home_uuid, boot
            menu entries without bootloader): hide it
  label     translated title of the setting
  help      translated explanation, one paragraph, to wrap
  warning   translated warning (data loss, network...), often empty

bool settings take 'auto' (yes) or an empty value (no). Run describe
again after each change: active flags and types follow the values.

  tazinst options <key> [file]

Values a choice, partition, file or bool setting can take:

  value  label

An empty value is valid when listed (no format, no bootloader...).
text and password settings have no options.

  tazinst set <key> <value> [file]
  tazinst unset <key> [file]
  tazinst get <key> [file]

Change, clear or read one value (plain text output).

Partitions
----------

  tazinst list partitions

  device  bytes  size  fstype  label  disk  removable  role  mountpoint  model
  transport  system

  removable  1 for a removable disk, USB and SD cards included
  role       esp, bios_boot, extended, swap, media (iso9660) or data
  transport  usb, mmc or empty
  system     the system a data partition holds (PRETTY_NAME of its
             etc/os-release), empty if none; needs root, the partition
             is mounted read only to look

Only data partitions are offered as options, never one the running
system uses (mounted outside /media and /mnt), nor one another setting
already took (root, source, home, Windows).

Validation
----------

  tazinst --machine check [key] [file]

One record per active setting, or for the given key:

  key  status  message

  status  ok, warning (the install can go on) or error

Plan
----

  tazinst plan [file]

What execute will do, for a summary page, one action per record:

  mode        install|upgrade
  source      media  source
  format      partition  fstype
  clean       partition  (install without format, /home is kept)
  home        partition
  hostname    name
  user        login
  upgrade     partition  kept directories
  bootloader  disk  grub targets (i386-pc, x86_64-efi, i386-efi)
  liveboot    partition
  webboot     partition
  winboot     partition

Execute
-------

  tazinst --machine execute [file]

Runs as root. Records are streamed on stdout while installing:

  progress  percent  message   step of the install, 1 to 100
  info      message            detail line
  error     code     message   the install stopped

The exit status is 0 on success, else the error code:

  1  parameters error        6  no SliTaz system to upgrade
  2  install file error      7  another instance is running
  3  source error            8  internal error
  4  target error            9  cancelled by user
  5  missing resource

Send SIGTERM (or SIGINT) to cancel: tazinst unmounts everything and
exits with an 'error 9' record. The full log is in /var/log/tazinst.log
and is copied to the installed system.
