'\" t
.\"     Title: plinth
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 06/06/2023
.\"    Manual: FreedomBox
.\"    Source:  
.\"  Language: English
.\"
.TH "PLINTH" "1" "06/06/2023" "" "FreedomBox"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
plinth \- a web front end for administering FreedomBox
.SH "SYNOPSIS"
.HP \w'\fBplinth\fR\ 'u
\fBplinth\fR [\fB\-h,\ \fR\fB\-\-help\fR] [\fB\-\-server_dir\fR\ {SERVER_DIR}] [\fB\-\-develop\fR] [\fB\-\-diagnose\fR] [\fB\-\-setup\fR\ [application...]] [\fB\-\-setup\-no\-install\fR\ [application...]] [\fB\-\-list\-dependencies\fR\ [application...]]
.SH "DESCRIPTION"
.PP
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\&.
.PP
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\&.
.SH "OPTIONS"
.PP
\fB\-\-server_dir SERVER_DIR\fR
.RS 4
This the URL fragment under which Plinth will provide its services\&. Plinth is shipped with a default value of
/plinth\&. This means that Plinth will be available as http://localhost:8000/plinth by default\&.
.RE
.PP
\fB\-\-develop\fR
.RS 4
Enable development mode\&. Use develop\&.config and action scripts from the current working directory\&. Enables extra debug messages, enable Django debug mode for detailed error pages 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\&.
.RE
.PP
\fB\-\-diagnose\fR
.RS 4
If provided, Plinth loads modules, performs initialization but does start the web server\&. Instead it runs diagnostic tests on each module and exits\&.
.RE
.PP
\fB\-\-setup\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-setup\-no\-install\fR
.RS 4
Same as
\fB\-\-setup\fR
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\&.
.RE
.PP
\fB\-\-list\-dependencies\fR
.RS 4
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 \*(Aq*\*(Aq 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\&.
.RE
.SH "CONFIGURATION"
.PP
Plinth reads various configuration options from the files
/usr/share/freedombox/freedombox\&.config,
/usr/share/freedombox/freedombox\&.config\&.d/*\&.config,
/etc/plinth/plinth\&.config,
/etc/plinth/plinth\&.config\&.d/*\&.config,
/etc/freedombox/freedombox\&.config
and
/etc/freedombox/freedombox\&.config\&.d/*\&.config
in that order\&. Options in a file read later override options specified earlier\&.
/etc/plinth/
locations are deprecated\&.
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Start Plinth with default options\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ plinth
.fi
.if n \{\
.RE
.\}
.PP
Run Plinth as guided by configuration file\&.
.PP
\fBExample\ \&2.\ \&Run Plinth with different URL prefix\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ plinth \-\-server_dir=\*(Aq/myurl\*(Aq
.fi
.if n \{\
.RE
.\}
.PP
Run Plinth with the \*(Aq/myurl\*(Aq prefix\&. Note that Apache forwards requests to \*(Aq/plinth\*(Aq by default, so /myurl is not accessible outside of your FreedomBox without adapting the apache configuration\&.
.PP
\fBExample\ \&3.\ \&Run Plinth in development mode\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ plinth \-\-develop
.fi
.if n \{\
.RE
.\}
.PP
Run in development mode on the terminal\&. Enable auto\-reloading and more extensive debugging\&.
.SH "BUGS"
.PP
See
\m[blue]\fBPlinth issue tracker\fR\m[]\&\s-2\u[1]\d\s+2
for a full list of known issues and TODO items\&.
.SH "AUTHOR"
.PP
Plinth Developers
.SH "NOTES"
.IP " 1." 4
Plinth issue tracker
.RS 4
\%https://salsa.debian.org/freedombox-team/freedombox/issues
.RE