From: Michael Orlitzky <michael@orlitzky.com>
Date: Tue, 24 Feb 2026 03:05:03 +0000 (-0500)
Subject: doc/README.rst: add a reStructuredText README, mainly for Codeberg
X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=b44f098d6ff43bb5e7070fd1686398ba38cc071f;p=untangle-https-backup.git

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

diff --git a/doc/README.rst b/doc/README.rst
new file mode 100644
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>`_.