From 7c0fa00536e24e8638fd8f1d8b40f231beac803b Mon Sep 17 00:00:00 2001 From: Sunil Mohan Adapa Date: Tue, 16 Sep 2025 14:40:55 -0700 Subject: [PATCH] doc: Add manual page for freedombox-cmd Tests: - 'make -C doc' succeeds. 'man doc/freedombox-cmd.1' shows the manual page. - Building and install .deb package installs the manual page to appropriate location. Signed-off-by: Sunil Mohan Adapa Reviewed-by: Veiko Aasa --- .gitignore | 2 +- debian/freedombox.manpages | 1 + doc/Makefile | 2 +- doc/freedombox-cmd.xml | 160 +++++++++++++++++++++++++++++++++++++ 4 files changed, 163 insertions(+), 2 deletions(-) create mode 100644 doc/freedombox-cmd.xml diff --git a/.gitignore b/.gitignore index 812d5c4ad..9440cf52b 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,7 @@ doc/manual/*/*.pdf doc/manual/*/*.html doc/manual/*/*.xml -doc/plinth.1 +doc/*.1 doc/dev/_build \#* .#* diff --git a/debian/freedombox.manpages b/debian/freedombox.manpages index 1b517d232..f96cd2ce6 100644 --- a/debian/freedombox.manpages +++ b/debian/freedombox.manpages @@ -1 +1,2 @@ +./doc/freedombox-cmd.1 ./doc/plinth.1 diff --git a/doc/Makefile b/doc/Makefile index 95489391b..37ccf8465 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -13,7 +13,7 @@ SCRIPTS_DIR=scripts manual-pdfs=$(foreach lang,$(MANUAL_LANGUAGES),manual/$(lang)/freedombox-manual.pdf) manual-xmls=$(patsubst %.pdf,%.xml,$(manual-pdfs)) -OUTPUTS=$(manual-pdfs) plinth.1 +OUTPUTS=$(manual-pdfs) plinth.1 freedombox-cmd.1 INSTALL_OPTS=-D --mode=644 diff --git a/doc/freedombox-cmd.xml b/doc/freedombox-cmd.xml new file mode 100644 index 000000000..64eb6d3f4 --- /dev/null +++ b/doc/freedombox-cmd.xml @@ -0,0 +1,160 @@ + + + + + + freedombox-cmd + 1 + FreedomBox Command Line Utility + + + + + freedombox-cmd + + command line utility to perform FreedomBox operations + + + + + + freedombox-cmd + + module + action + + + + + + Description + + FreedomBox is a community project to develop, design and promote + personal servers running free software for private, personal + communications. It is a networking appliance designed to allow + interfacing with the rest of the Internet under conditions of + protected privacy and data security. It hosts applications such + as blog, wiki, website, social network, email, web proxy and a + Tor relay on a device that can replace a wireless router so that + data stays with the users. + + + freedombox-cmd is a command line interface to some of the operations + performed by FreedomBox. It is typically not needed by the end users who + use FreedomBox's web interface. The command may be used in some cases + while debugging problems, especially where the web interface is not + accessible or when a piece of functionality that is not provided in the + web interface needs to be triggered. + + + The command is simply a client to the FreedomBox's privileged daemon and + relays user's request to it. It waits for the request to complete and + prints the output of the operation or an error message collected form the + daemon. The daemon only allows connections from an pre-allowed list of + user accounts. So, be sure to run the command as 'root' superuser. + + + + + Options + + + + + + Name of the module from which to execute an action. + + + + + + + + Name of the action to execute. It should found in the provided + module. + + + + + + + + Don't try to read the arguments to the command on the standard + input. Instead, assume that the operation does not have any + arguments and execute the method without arguments. + + + + + + + + Show brief help about arguments allowed for this command. + + + + + + + + Examples + + + Re-run FreedomBox network setup + $ sudo freedombox-cmd networks setup --no-args + + When FreedomBox starts for the first time, it will setup Network Manager + connections suitable for the hardware found. If you wish to re-create + these connections at a later time, you can re-run setup for the Networks + app using the web interface or run this command on a terminal. + + + + + Delete a user account from LDAP database + $ echo '{"args": ["USERNAME", "AUTH_USER", "AUTH_PASSWORD"], "kwargs": {}}' | sudo freedombox-cmd users remove_user + + USERNAME is the name of the user account that must be removed. AUTH_USER + is name of the user account that is authorizing this operation. + AUTH_PASSWORD is the password for user account that is authorizing this + operation. This operation may be needed if FreedomBox's sqlite3 database + is wiped, removing the user accounts in the database but the + corresponding entries from LDAP database are not removed. A new user + with that name can't be created until the LDAP account is also removed. + + + + + Set the logging mode to persistent + $ echo '{"args": ["persistent"], "kwargs": {}}' | sudo freedombox-cmd config set_logging_mode + + By default, FreedomBox sets up systemd-journald to 'volatile' logging. + This means that logs will not be stored on the disk and will be lost + after a reboot. If you are tackling a problem and wish to store the logs + persistently, you can change the setting in the web interface or run + this command. + + + + + + Bugs + + See FreedomBox + issue tracker for a full list of known issues and TODO items. + + + + + Author + + + FreedomBox Developers + Original author + + + +