doc/README.rst: add a reStructuredText README, mainly for Codeberg

diff --git a/doc/README.rst b/doc/README.rst
new file mode 100644 (file)
index 0000000..f744624
--- /dev/null
+++ b/doc/README.rst
@@ -0,0 +1,92 @@
+What is it?
+===========
+
+A CLI utility to back up `Untangle <https://www.untangle.com/>`_
+configurations.
+
+The Untangle web UI provides a way to create backups of the local
+configuration. However, if you manage enough Untangle installations,
+it becomes impractical to log in to each one and navigate to the
+backups in a browser. The *untangle-https-backup* program automates
+that process for a list of installations contained in a configuration
+file.
+
+
+Usage
+=====
+
+.. code-block:: console
+
+  $ untangle-https-backup [--config-file <INI file>]
+
+
+Input/Output
+============
+
+It takes no input; the program's behavior is entirely determined by
+its configuration (INI) file. Errors are output to stderr; otherwise,
+silence is golden.
+
+
+Configuration file
+==================
+
+The configuration file is an INI-style list of Untangle installations
+to back up. An example entry is,
+
+.. code-block:: ini
+
+  [Test installation]
+  host = 192.168.1.100
+  username = testuser
+  password = hunter2
+
+There are currently five parameters that may be set for each
+installation:
+
+host (required)
+  The hostname or IP address where the Untangle web UI is available.
+username
+  (default: admin) The Untangle admin username.
+password (required)
+  The Untangle admin password.
+version
+  (default: 14.1) The version of Untangle running on this host. Note
+  that new version options are added only when compatibility breaks.
+verify_cert
+  (default: False) Whether or not to verify the site's SSL
+  certificate, either ``True`` or ``False``.
+timeout
+  (default: 300) How long to wait for socket operations to complete,
+  in seconds.
+
+
+Options
+=======
+
+--config-file, -c
+  (default: /etc/untangle-https-backup.ini) Path to the configuration
+  file.
+
+
+Examples
+========
+
+It is difficult to invoke *untangle-https-backup* incorrectly:
+
+.. code-block:: console
+
+  $ untangle-https-backup
+
+Specify an alternate configuration file:
+
+.. code-block:: console
+
+  $ untangle-https-backup --config-file /etc/foo.ini
+
+
+How to report bugs
+==================
+
+Email them to me at michael@orlitzky.com, or report them on `Codeberg
+<https://codeberg.org/mjo/untangle-https-backup/issues>`_.