mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-03-11 09:04:54 +00:00
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 <sunil@medhas.org> Reviewed-by: Veiko Aasa <veiko17@disroot.org>
This commit is contained in:
Sunil Mohan Adapa
Veiko Aasa
parent
c2d5d1d3c8
commit
7c0fa00536
2
.gitignore
vendored
2
.gitignore
vendored
@ -4,7 +4,7 @@
|
||||
doc/manual/*/*.pdf
|
||||
doc/manual/*/*.html
|
||||
doc/manual/*/*.xml
|
||||
doc/plinth.1
|
||||
doc/*.1
|
||||
doc/dev/_build
|
||||
\#*
|
||||
.#*
|
||||
|
||||
1
debian/freedombox.manpages
vendored
1
debian/freedombox.manpages
vendored
@ -1 +1,2 @@
|
||||
./doc/freedombox-cmd.1
|
||||
./doc/plinth.1
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
160
doc/freedombox-cmd.xml
Normal file
160
doc/freedombox-cmd.xml
Normal file
@ -0,0 +1,160 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.docbook.org/xml/4.4/docbookx.dtd">
|
||||
<!--
|
||||
# SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
<refentry>
|
||||
<refmeta>
|
||||
<refentrytitle><application>freedombox-cmd</application></refentrytitle>
|
||||
<manvolnum>1</manvolnum>
|
||||
<refmiscinfo class="manual">FreedomBox Command Line Utility</refmiscinfo>
|
||||
<refmiscinfo class="version"> </refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname><application>freedombox-cmd</application></refname>
|
||||
<refpurpose>
|
||||
command line utility to perform FreedomBox operations
|
||||
</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<cmdsynopsis>
|
||||
<command>freedombox-cmd</command>
|
||||
<arg><option>-h, </option><option>--help</option></arg>
|
||||
<arg choice="req">module</arg>
|
||||
<arg choice="req">action</arg>
|
||||
<arg><option>--no-args</option></arg>
|
||||
</cmdsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Options</title>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><option>module</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Name of the module from which to execute an action.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>action</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Name of the action to execute. It should found in the provided
|
||||
module.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>--no-args</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>--help</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Show brief help about arguments allowed for this command.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Examples</title>
|
||||
|
||||
<example>
|
||||
<title>Re-run FreedomBox network setup</title>
|
||||
<synopsis>$ sudo freedombox-cmd networks setup --no-args</synopsis>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Delete a user account from LDAP database</title>
|
||||
<synopsis>$ echo '{"args": ["USERNAME", "AUTH_USER", "AUTH_PASSWORD"], "kwargs": {}}' | sudo freedombox-cmd users remove_user</synopsis>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Set the logging mode to persistent</title>
|
||||
<synopsis>$ echo '{"args": ["persistent"], "kwargs": {}}' | sudo freedombox-cmd config set_logging_mode</synopsis>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</example>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Bugs</title>
|
||||
<para>
|
||||
See <ulink
|
||||
url="https://salsa.debian.org/freedombox-team/freedombox/issues">FreedomBox
|
||||
issue tracker</ulink> for a full list of known issues and TODO items.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Author</title>
|
||||
<para>
|
||||
<author>
|
||||
<firstname>FreedomBox Developers</firstname>
|
||||
<contrib>Original author</contrib>
|
||||
</author>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
Loading…
x
Reference in New Issue
Block a user