mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-01-21 07:55:00 +00:00
d2e987ef3c
Found with [codespell](https://github.com/codespell-project/codespell/) Reviewed-by: Sunil Mohan Adapa <sunil@medhas.org>
242 lines
9.0 KiB
XML
242 lines
9.0 KiB
XML
<?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">
|
|
<!--
|
|
#
|
|
# This file is part of FreedomBox.
|
|
#
|
|
# This program is free software: you can redistribute it and/or modify
|
|
# it under the terms of the GNU Affero General Public License as
|
|
# published by the Free Software Foundation, either version 3 of the
|
|
# License, or (at your option) any later version.
|
|
#
|
|
# This program is distributed in the hope that it will be useful,
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
# GNU Affero General Public License for more details.
|
|
#
|
|
# You should have received a copy of the GNU Affero General Public License
|
|
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
#
|
|
-->
|
|
<refentry>
|
|
<refmeta>
|
|
<refentrytitle><application>plinth</application></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">FreedomBox</refmiscinfo>
|
|
<refmiscinfo class="version"> </refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname><application>plinth</application></refname>
|
|
<refpurpose>
|
|
a web front end for administering FreedomBox
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>plinth</command>
|
|
<arg><option>-h, </option><option>--help</option></arg>
|
|
<arg><option>--server_dir</option><arg choice="req">SERVER_DIR</arg></arg>
|
|
<arg><option>--develop</option></arg>
|
|
<arg><option>--diagnose</option></arg>
|
|
<arg>
|
|
<option>--setup</option>
|
|
<arg choice="opt" rep="repeat">application</arg>
|
|
</arg>
|
|
<arg>
|
|
<option>--setup-no-install</option>
|
|
<arg choice="opt" rep="repeat">application</arg>
|
|
</arg>
|
|
<arg>
|
|
<option>--list-dependencies</option>
|
|
<arg choice="opt" rep="repeat">application</arg>
|
|
</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>
|
|
Plinth is a web interface to administer the functions of the
|
|
FreedomBox. It is extensible and is made of modules. Each
|
|
module provides a simplified user interface to control the
|
|
underlying functionality of a specific application of
|
|
FreedomBox. As FreedomBox can act as a wireless router, it is
|
|
possible to configure networking from Plinth. Plinth allows
|
|
configuration of basic system parameters such as time zone,
|
|
hostname and automatic upgrade settings.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>--server_dir SERVER_DIR</option></term>
|
|
<listitem>
|
|
<para>
|
|
This the URL fragment under which Plinth will provide its
|
|
services. By default the value from
|
|
<filename>plinth.config</filename> is used. Plinth is
|
|
shipped with a value of <filename>/plinth</filename> in
|
|
<filename>/etc/plinth/plinth.config</filename>. This
|
|
means that Plinth will be available as
|
|
http://localhost:8000/plinth by default.
|
|
When <filename>/etc/plinth/plinth.config</filename> is not
|
|
available, <filename>plinth.config</filename> from the current
|
|
working directory is used.
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--develop</option></term>
|
|
<listitem>
|
|
<para>
|
|
Enable development mode. Use plinth.config and the actions_dir
|
|
of the current working directory. Enables extra debug messages,
|
|
enable Django debug mode for detailed error pages and and turn off
|
|
Django security features. Monitor source files for changes and
|
|
restart Plinth on modifications. Die if there is an error during
|
|
module initialization.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--diagnose</option></term>
|
|
<listitem>
|
|
<para>
|
|
If provided, Plinth loads modules, performs initialization
|
|
but does start the web server. Instead it runs diagnostic
|
|
tests on each module and exits.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--setup</option></term>
|
|
<listitem>
|
|
<para>
|
|
Perform application setup operations and exit. Setting up
|
|
an application involves installing packages required for
|
|
that application and performing pre and post install
|
|
configuration setups. If no application is provided,
|
|
setup all applications which describe themselves as
|
|
essential. If a list of applications is provided, setup
|
|
only those applications.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--setup-no-install</option></term>
|
|
<listitem>
|
|
<para>
|
|
Same as <option>--setup</option> but no new Debian
|
|
packages are installed during setup. When a package needs
|
|
to be installed, a check is done to make sure the package
|
|
is already installed. If the package is already
|
|
installed, no upgrade is performed and setup skips this
|
|
step and proceeds to next operation. If the package is
|
|
not installed an error is raised and setup process halts.
|
|
This is option is useful for running setup during post
|
|
installation script of a Debian package. Essential
|
|
packages are added as dependencies for the Debian package
|
|
and then setup process is executed from post install
|
|
script of the Debian package.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--list-dependencies</option></term>
|
|
<listitem>
|
|
<para>
|
|
For the list of provided applications, print the list of
|
|
packages needed by the applications. If no application is
|
|
provided as additional argument, then print list of
|
|
packages needed by all essential applications. If '*' is
|
|
provided in the list of the applications, then list of
|
|
packages needed by all applications will be printed.
|
|
Although, packages are installed when the application is
|
|
first accessed, this list will be useful for adding list
|
|
of dependencies to a Debian package and to get a list of
|
|
all interesting packages. Other output may be printed on
|
|
stderr and should be ignored.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Configuration</title>
|
|
<para>
|
|
Plinth reads various configuration options from the file
|
|
<filename>/etc/plinth/plinth.config</filename>. If this file is
|
|
not present, then it reads configuration file
|
|
<filename>./plinth.config</filename> from the current directory.
|
|
This is mainly meant to make Plinth work with configuration from
|
|
source code directory for debugging purposes.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<example>
|
|
<title>Start Plinth with default options</title>
|
|
<synopsis>$ plinth</synopsis>
|
|
<para>
|
|
Run Plinth as guided by configuration file.
|
|
</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Run Plinth with different URL prefix</title>
|
|
<synopsis>$ plinth --server_dir='/myurl'</synopsis>
|
|
<para>
|
|
Run Plinth with the '/myurl' prefix. Note that Apache forwards requests
|
|
to '/plinth' by default, so /myurl is not accessible outside of your
|
|
FreedomBox without adapting the apache configuration.
|
|
</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Run Plinth in development mode</title>
|
|
<synopsis>$ plinth --develop</synopsis>
|
|
<para>
|
|
Run in development mode on the terminal. Enable auto-reloading and
|
|
more extensive debugging.
|
|
</para>
|
|
</example>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Bugs</title>
|
|
<para>
|
|
See <ulink
|
|
url="https://salsa.debian.org/freedombox-team/plinth/issues">Plinth
|
|
issue tracker</ulink> for a full list of known issues and TODO items.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Author</title>
|
|
<para>
|
|
<author>
|
|
<firstname>Plinth Developers</firstname>
|
|
<contrib>Original author</contrib>
|
|
</author>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|