1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
<?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 configuraiton 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>
|
