]> git.mxchange.org Git - friendica.git/blob - doc/Settings.md
Merge pull request #12046 from nupplaphil/bug/DI_missing
[friendica.git] / doc / Settings.md
1 # Settings
2
3 * [Home](help)
4
5 If you are the admin of a Friendica node, you have access to the **Admin Panel** where you can configure your Friendica node.
6
7 ## Overview
8
9 In the main page of the admin panel you will see an information summary about your node.
10
11 ### Queues
12
13 The three numbers shown are respectively:
14 - The retry queue: These outgoing messages couldn't be received by the remote host, and will be resent at longer intervals before being dropped entirely after 30 days.
15 - The deferred queue: These internal tasks failed and will be retried at most 14 times.
16 - The task queue: These internal tasks are queued for execution during the next background worker run.
17
18 ### Additional information
19
20 Then you get an overview of the accounts on your node, which can be moderated in the "Users" section of the panel.
21 As well as an overview of the currently active addons.
22 The list is linked, so you can have quick access to the Addon settings.
23 And finally you are informed about the version of Friendica you have installed.
24 If you contact the developers with a bug or problem, please also mention the version of your node.
25
26 The admin panel is separated into subsections accessible from the side bar of the panel.
27
28 ## Site
29
30 This section of the admin panel contains the main configuration of your Friendica node.
31 It is separated into several sub-section beginning with the basic settings at the top, advancing towards the bottom of the page.
32
33 Most configuration options have a help text in the admin panel.
34 Therefore this document does not yet cover all the options
35
36 ### Basic Settings
37
38 #### Banner/Logo
39
40 Set the content for the site banner.
41 The default logo is the Friendica logo and name.
42 You may wish to provide HTML/CSS to style and/or position this content, as it may not be themed by default.
43
44 #### Language
45
46 This option will set the default language for the node.
47 It is used as fall back setting should Friendica fail to recognize the visitors preferences and can be overwritten by user settings.
48
49 The Friendica community offers some translations.
50 Some more complete then others.
51 See [this help page](/help/translations) for more information about the translation process.
52
53 #### System Theme
54
55 Choose a theme to be the default system theme.
56 This can be over-ridden by user profiles.
57 Default theme is `vier` at the moment.
58
59 You may also want to set a special theme for mobile interfaces.
60 Which may or may not be necessary depending of the mobile friendliness of the desktop theme you have chosen.
61 The `vier` theme for instance is mobile friendly.
62
63 ### Registration
64
65 #### Register policy
66
67 With this drop down selector you can set the nodes registration policy.
68 You can chose between the following modes:
69
70 * **open**: Everybody can register a new account and start using it right away.
71 * **requires approval**: Everybody can register a new account, but the admin has to approve it before it can be used.
72 * **closed**: No new registrations are possible.
73
74 ##### Invitation based registry
75
76 Additionally to the setting in the admin panel, you can decide if registrations are only possible using an invitation code or not.
77 To enable invitation based registration, you have to set the `invitation_only` setting to `true` in the `system` section of the [config/local.config.php](/help/Config) file.
78 If you want to use this method, the registration policy has to be set to either *open* or *requires approval*.
79
80 #### Check Full Names
81
82 You may find a lot of spammers trying to register on your site.
83 During testing we discovered that since these registrations were automatic, the "Full Name" field was often set to just an account name with no space between first and last name.
84 If you would like to support people with only one name as their full name, you may change this setting to true.
85 Default is false.
86
87 #### OpenID
88
89 By default, OpenID may be used for both registration and logins.
90 If you do not wish to make OpenID facilities available on your system (at all), set 'no_openid' to true.
91 Default is false.
92
93 #### Multiple Registrations
94
95 The ability to create "Pages" requires a person to register more than once.
96 Your site configuration can block registration (or require approval to register).
97 By default, logged in users can register additional accounts for use as pages.
98 These will still require approval if the registration policy is set to *require approval*
99 You may prohibit logged in users from creating additional accounts by setting *block multiple registrations* to true.
100 Default is false.
101
102 ### File upload
103
104 #### File storage backend
105
106 Set the backend used by Friendica to store uploaded file data.
107 Two storage backends are avaiable with Friendica:
108
109 - **Database** : Data is stored in a dedicated table in database (`storage`)
110 - **Filesystem** : Data is stored as file on the filesystem.
111
112 More storage backends can be avaiable from third-party addons.
113 If you use those, please refer to the documentation of those addons for further information.
114
115 Default value is 'Database (legacy)': it's the legacy way used to store data directly in database.
116
117 Existing data can be moved to the current active backend using the ['storage move' console command](help/tools)
118
119 If selected backend has configurable options, new fields are shown here.
120
121 ##### Filesystem: Storage base path
122
123 The base path where Filesystem storage backend saves data.
124
125 For maximum security, this path should be outside the folder tree served by the web server: this way files can't be downloaded bypassing the privacy checks.
126
127 Default value is `storage`, that is the `storage` folder in Friendica code root folder.
128
129
130 #### Maximum Image Size
131
132 Maximum size in bytes of uploaded images.
133 The default is set to 0, which means no limits.
134
135 ### Policies
136
137 #### Global Directory
138
139 This configures the URL to update the global directory, and is supplied in the default configuration.
140 The undocumented part is that if this is not set, the global directory is completely unavailable to the application.
141 This allows a private community to be completely isolated from the global network.
142
143 #### Force Publish
144
145 By default, each user can choose on their Settings page whether or not to have their profile published in the site directory.
146 This setting forces all profiles on this site to be listed in the site directory and there is no option provided to the user to change it.
147 Default is false.
148
149 #### Block Public
150
151 Set to true to block public access to all otherwise public personal pages on this site unless you are currently logged in.
152 This blocks the viewing of profiles, friends, photos, the site directory and search pages to unauthorised persons.
153 A side effect is that entries from this site will not appear in the global directory.
154 We recommend specifically disabling that also (setting is described elsewhere on this page).
155 Note: this is specifically for sites that desire to be "standalone" and do not wish to be connected to any other Friendica sites.
156 Unauthorised persons will also not be able to request friendship with site members.
157 Default is false.
158 Available in version 2.2 or greater.
159
160 #### Community pages for Visitors
161
162 The community pages show all public postings, separated by their origin being local or the entire network.
163 With this setting you can select which community pages will be shown to visitors of your Friendica node.
164 Your local users will always have access to both pages.
165
166 **Note**: Several settings, like users hiding their contacts from the public will prevent the postings to show up on the global community page.
167
168 #### Allowed Friend Domains
169
170 Comma separated list of domains which are allowed to establish friendships with this site.
171 Wildcards are accepted.
172 By default, any (valid) domain may establish friendships with this site.
173
174 This is useful if you want to setup a closed network for educational groups, cooperatives and similar communities that don't want to communicate with the rest of the network.
175
176 #### Allowed Email Domains
177
178 Comma separated list of domains which are allowed in email addresses for registrations to this site.
179 This can lockout those who are not part of this organisation from registering here.
180 Wildcards are accepted.
181 By default, any (valid) email address is allowed in registrations.
182
183 #### Allow Users to set remote_self
184
185 If you enable the `Allow Users to set remote_self` users can select Atom feeds from their contact list being their *remote self* in the contact settings.
186 Which means that postings by the remote self are automatically reposted by Friendica in their names.
187
188 This feature can be used to let the user mirror e.g. blog postings into their Friendica postings.
189 It is disabled by default, as it causes additional load on the server and may be misused to distribute SPAM.
190
191 As admin of the node you can also set this flag directly in the database.
192 Before doing so, you should be sure you know what you do and have a backup of the database.
193
194 #### Explicit Content
195
196 If you are running a node with explicit content, you can announce this with this option.
197 When checked an information flag will be set in the published information about your node.
198 (Should *Publish Server Information* be enabled.)
199
200 Additionally a note will be displayed on the registration page for new users.
201
202 ### Advanced
203
204 #### Proxy Configuration Settings
205
206 If your site uses a proxy to connect to the internet, you may use these settings to communicate with the outside world.
207 The outside world still needs to be able to see your website, or this will not be very useful.
208
209 #### Network Timeout
210
211 How long to wait on a network communication before timing out.
212 Value is in seconds.
213 Default is 60 seconds.
214 Set to 0 for unlimited (not recommended).
215
216 #### Verify SSL Certificates
217
218 By default Friendica allows SSL communication between websites that have "self-signed" SSL certificates.
219 For the widest compatibility with browsers and other networks we do not recommend using self-signed certificates, but we will not prevent you from using them.
220 SSL encrypts all the data transmitted between sites (and to your browser).
221 This allows you to have completely encrypted communications, and also protect your login session from hijacking.
222 Self-signed certificates can be generated for free, without paying top-dollar for a website SSL certificate.
223 However these aren't looked upon favourably in the security community because they can be subject to so-called "man-in-the-middle" attacks.
224 If you wish, you can turn on strict certificate checking.
225 This will mean you cannot connect (at all) to self-signed SSL sites.
226
227 #### Check upstream version
228
229 If this option is enabled your Friendica node will check the upstream version once per day from the github repository.
230 You can select if the stable version or the development version should be checked out.
231 If there is a new version published, you will get notified in the admin panel summary page.
232
233 ### Auto Discovered Contact Directory
234
235 ### Performance
236
237 ### Worker
238
239 This section allows you to configure the background process that is triggered by the `cron` job that was created during the installation.
240 The process does check the available system resources before creating a new worker for a task.
241 Because of this, it may happen that the maximum number of worker processes you allow will not be reached.
242
243 The tasks for the background process have priorities.
244 To guarantee that important tasks are executed even though the system has a lot of work to do, it is useful to enable the *fastlane*.
245
246 ### Relocate
247
248 ## Users
249
250 This section of the panel let the admin control the users registered on the node.
251
252 If you have selected "Requires approval" for the *Register policy* in the general nodes configuration, new registrations will be listed at the top of the page.
253 There the admin can then approve or disapprove the request.
254
255 Below the new registration block the current accounts on the Friendica node are listed.
256 You can sort the user list by name, email, registration date, date of last login, date of last posting and the account type.
257 Here the admin can also block/unblock users from accessing the node or delete the accounts entirely.
258
259 In the last section of the page admins can create new accounts on the node.
260 The password for the new account will be send by email to the chosen email address.
261
262 ## Addons
263
264 This page is for selecting and configuration of extensions for Friendica which have to be placed into the `/addon` subdirectory of your Friendica installation.
265 You are presented with a long list of available addons.
266 The name of each addon is linked to a separate page for that addon which offers more information and configuration possibilities.
267 Also shown is the version of the addon and an indicator if the addon is currently active or not.
268
269 When you update your node and the addons they may have to be reloaded.
270 To simplify this process there is a button at the top of the page to reload all active Addons.
271
272 ## Themes
273
274 The Themes section of the admin panel works similar to the Addons section but let you control the themes on your Friendica node.
275 Each theme has a dedicated subpage showing the current status, some information about the theme and a screen-shot of the Friendica interface using the theme.
276 Should the theme offer special settings, admins can set a global default value here.
277
278 You can activate and deactivate themes on their dedicated sub-pages thus making them available for the users of the node.
279 To select a default theme for the Friendica node, see the *Site* section of the admin panel.
280
281 ## Additional Features
282
283 There are several optional features in Friendica like the *dislike* button.
284 In this section of the admin panel you can select a default setting for your node and eventually fix it, so users cannot change the setting anymore.
285
286 ## DB Updates
287
288 Should the database structure of Friendica change, it will apply the changes automatically.
289 In case you are suspecting the update might not have worked, you can use this section of the admin panel to check the situation.
290
291 ## Inspect Queue
292
293 In the admin panel summary there are two numbers for the message queues.
294 The second number represents messages which could not be delivered and are queued for later retry.
295 If this number goes sky-rocking you might ask yourself which recipient is not receiving.
296
297 Behind the inspect queue section of the admin panel you will find a list of the messages that could not be delivered.
298 The listing is sorted by the recipient name so identifying potential broken communication lines should be simple.
299 These lines might be broken for various reasons.
300 The receiving end might be off-line, there might be a high system load and so on.
301
302 Don't panic!
303 Friendica will not queue messages for all time but will sort out *dead* nodes automatically after a while and remove messages from the queue then.
304
305 ## Server Blocklist
306
307 This page allows to block all communications (inbound and outbound) with a specific domain name.
308 Each blocked domain entry requires a reason that will be displayed on the [friendica](/friendica) page.
309 Matching is exact, blocking a domain doesn't block subdomains.
310
311 ## Federation Statistics
312
313 The federation statistics page gives you a short summery of the nodes/servers/pods of the decentralized social network federation your node knows.
314 These numbers are not complete and only contain nodes from networks Friendica federates directly with.
315
316 ## Delete Item
317
318 Using this page an admin can delete postings and eventually associated discussion threads from their Friendica node.
319 To do so, they need to know the GUID of the posting.
320 This can be found on the `/display` page of the posting, it is the last part of the URL displayed in the browsers navigation bar.
321 You can get to the `/display` page by following the *Link to source*.
322
323 ## Addon Features
324
325 Some of the addons you can install for your Friendica node have settings which have to be set by the admin.
326 All those addons will be listed in this area of the admin panels side bar with their names.
327
328 ## Logs
329
330 The log section of the admin panel is separated into two pages.
331 On the first, following the "log" link, you can configure how much Friendica shall log.
332 And on the second you can read the log.
333
334 You should not place your logs into any directory that is accessible from the web.
335 If you have to, and you are using the default configuration from Apache, you should choose a name for the logfile ending in ``.log`` or ``.out``.
336 Should you use another web server, please make sure that you have the correct access rules in place so that your log files are not accessible.
337
338 There are five different log levels: Normal, Trace, Debug, Data and All.
339 Specifying different verbosity of information and data written out to the log file.
340 Normally you should not need to log at all.
341 The *DEBUG* level will show a good deal of information about system activity but will not include detailed data.
342 In the *ALL* level Friendica will log everything to the file.
343 But due to the volume of information we recommend only enabling this when you are tracking down a specific problem.
344
345 **The amount of data can grow the filesize of the logfile quickly**.
346 You should set up some kind of [log rotation](https://en.wikipedia.org/wiki/Log_rotation) to keep the log file from growing too big.
347
348 **Known Issues**: The filename ``friendica.log`` can cause problems depending on your server configuration (see [issue 2209](https://github.com/friendica/friendica/issues/2209)).
349
350 By default PHP warnings and error messages are suppressed.
351 If you want to enable those, you have to activate them in the ``config/local.config.php`` file.
352 Use the following settings to redirect PHP errors to a file.
353
354 Config:
355
356         error_reporting(E_ERROR | E_WARNING | E_PARSE );
357         ini_set('error_log','php.out');
358         ini_set('log_errors','1');
359         ini_set('display_errors', '0');
360
361 This will put all PHP errors in the file php.out (which must be writeable by the webserver).
362 Undeclared variables are occasionally referenced in the program and therefore we do not recommend using `E_NOTICE` or `E_ALL`.
363 The vast majority of issues reported at these levels are completely harmless.
364 Please report to the developers any errors you encounter in the logs using the recommended settings above.
365 They generally indicate issues which need to be resolved.
366
367 If you encounter a blank (white) page when using the application, view the PHP logs - as this almost always indicates an error has occurred.
368
369 ## Diagnostics
370
371 In this section of the admin panel you find two tools to investigate what Friendica sees for certain resources.
372 These tools can help to clarify communication problems.
373
374 For the *probe address* Friendica will display information for the address provided.
375
376 With the second tool *check webfinger* you can request information about the thing identified by a webfinger (`someone@example.com`).
377
378 # Exceptions to the rule
379
380 There are four exceptions to the rule, that all the config will be read from the data base.
381 These are the data base settings, the admin account settings, the path of PHP and information about an eventual installation of the node in a sub-directory of the (sub)domain.
382
383 ## DB Settings
384
385 With the following settings, you specify the data base server, the username and password for Friendica and the database to use.
386
387         'database' => [
388                 'hostname' => 'localhost',
389                 'username' => 'mysqlusername',
390                 'password' => 'mysqlpassword',
391                 'database' => 'mysqldatabasename',
392                 'charset' => 'utf8mb4',
393         ],
394
395 ## Admin users
396
397 You can set one, or more, accounts to be *Admin*.
398 By default this will be the one account you create during the installation process.
399 But you can expand the list of email addresses by any used email address you want.
400 Registration of new accounts with a listed email address is not possible.
401
402         'config' => [
403                 'admin_email' => 'you@example.com, buddy@example.com',
404         ],
405
406 ## PHP Path
407
408 Some of Friendica's processes are running in the background.
409 For this you need to specify the path to the PHP binary to be used.
410
411         'config' => [
412                 'php_path' => '/usr/bin/php',
413         ],
414
415 ## Subdirectory configuration
416
417 It is possible to install Friendica into a subdirectory of your web server.
418 We strongly discourage you from doing so, as this will break federation to other networks (e.g. Diaspora, GNU Social, Hubzilla)
419 Say you have a subdirectory for tests and put Friendica into a further subdirectory, the config would be:
420
421         'system' => [
422                 'urlpath' => 'tests/friendica',
423         ],
424
425 ## Other exceptions
426
427 Furthermore there are some experimental settings, you can read-up in the [Config values that can only be set in config/local.config.php](help/Config) section of the documentation.
428