Congegni/sintonia
7
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: rename documentation files

Browse source 
Co-authored-by: Zachary Klosko <zklosko@users.noreply.github.com>
This commit is contained in:
jo 2022-02-09 09:18:15 +01:00 • committed by Jonas L
parent 8d8e55f236
commit c4cdb94fab
34 changed files with 0 additions and 1341 deletions
Download patch file Download diff file Expand all files Collapse all files

65
docs/server-config/backing-up-the-server.md Normal file
View file

@ -0,0 +1,65 @@
---
layout: article
title: Backing Up Libretime
category: admin
---
> At the moment, there is not a way to automatically restore a Libretime backup.
> To restore a failed Libretime instance, install a fresh copy, go through the
> standard setup process, and reupload the backed-up media files. A _Watched Folders_
> feature is [currently in development](https://github.com/LibreTime/libretime/issues/70).
A backup script is supplied for your convenience in the _utils/_ folder of the Libretime repo.
Run it using:
```
sudo bash libretime-backup.sh # backs up to user's home folder
# or
sudo bash libretime-backup.sh /backupdir/
```
The backup process can be automated with Cron. Simply add the following to the root user's
crontab with `sudo crontab -e`:
```
0 0 1 * * /locationoflibretimerepo/libretime/backup.sh
```
> For more information on how Cron works, check out [this Redhat guide](https://www.redhat.com/sysadmin/automate-linux-tasks-cron).
If you wish to deploy your own backup solution, the following files and folders need to
be backed up.
```
/srv
/airtime
/stor
/imported - Successfully imported media
/organize - A temporary holding place for uploaded media as the importer works
/etc
/airtime
airtime.conf - The main Libretime configuration
icecast_pass - Holds the password for the Icecast server
liquidsoap.cfg - The main configuration file for Liquidsoap
```
In addition, you should keep a copy of the database current to the backup. The below code
can be used to export the Libretime database to a file.
```
sudo -u postgres pg_dumpall filename
# or to a zipped archive
sudo -u postgres pg_dumpall | gzip -c > archivename.gz
```
It is recommended to use an incremental backup technique to synchronize
the your LibreTime track library with a backup server regularly. (If
the backup server also contains an LibreTime installation, it should be possible
to switch playout to this second machine relatively quickly, in case of a
hardware failure or other emergency on the production server.)
Two notible backup tools are [rsync](http://rsync.samba.org/) (without version control) and
[rdiff-backup](http://www.nongnu.org/rdiff-backup/) (with version control). _rsync_ comes
preinstalled with Ubuntu Server.
> **Note:** Standard _rsync_ backups, which are used by the backup script, cannot restore files deleted in the backup itself

108
docs/server-config/freeipa.md Normal file
View file

@ -0,0 +1,108 @@
---
layout: article
title: FreeIPA Configuration
category: install
---
You can configure LibreTime to delegate all authentication to a FreeIPA server.
This allows you users to use their existing FreeIPA credentials. For this to
work you need to configure Apache to use `mod_authnz_pam` and `mod_intercept_form_submit`.
## Apache configuration {#apache}
After installing the needed modules you can set up Apache to intercept form logins and
check them against pam.
```apache
<Location /login>
InterceptFormPAMService http-libretime
InterceptFormLogin username
InterceptFormPassword password
InterceptFormLoginSkip admin
InterceptFormPasswordRedact on
InterceptFormLoginRealms INT.RABE.CH
Require pam-account http-libretime
</Location>
<Location />
<RequireAny>
<RequireAny>
Require pam-account http-libretime
Require all granted
</RequireAny>
<RequireAll>
Require expr %{REQUEST_URI} =~ /(index.php|login|favicon.ico|js|css|locale)/
Require all granted
</RequireAll>
</RequireAny>
</Location>
```
## PAM configuration {#pam}
The above configuration expects a PAM configuration for the `http-libretime` service.
To confiure this you need to create the file `/etc/pam.d/http-libretime` with the following contents.
```
auth required pam_sss.so
account required pam_sss.so
```
## LDAP configuration {#ldap}
LibreTime needs direct access to LDAP so it can fetch additional information. It does so with
a [system account](https://www.freeipa.org/page/HowTo/LDAP#System_Accounts) that you need to
set up beforehand.
You can configure everything pertaining to how LibreTime accesses LDAP in
`/etc/airtime/airtime.conf`. The default file has the following values you need to change.
```ini
#
# ----------------------------------------------------------------------
# L D A P
# ----------------------------------------------------------------------
#
# hostname: Hostname of LDAP server
#
# binddn: Complete DN of user used to bind to LDAP
#
# password: Password for binddn user
#
# account_domain: Domain part of username
#
# basedn: base search DN
#
# filter_field: Name of the uid field for searching
# Usually uid, may be cn
#
# groupmap_*: Map LibreTime user types to LDAP groups
# Lets LibreTime assign user types based on the
# group a given user is in.
#
[ldap]
hostname = ldap.example.org
binddn = 'uid=libretime,cn=sysaccounts,cn=etc,dc=int,dc=example,dc=org'
password = hackme
account_domain = INT.EXAMPLE.ORG
basedn = 'cn=users,cn=accounts,dc=int,dc=example,dc=org'
filter_field = uid
groupmap_guest = 'cn=guest,cn=groups,cn=accounts,dc=int,dc=example,dc=org'
groupmap_host = 'cn=host,cn=groups,cn=accounts,dc=int,dc=example,dc=org'
groupmap_program_manager = 'cn=program_manager,cn=groups,cn=accounts,dc=int,dc=example,dc=org'
groupmap_admin = 'cn=admins,cn=groups,cn=accounts,dc=int,dc=example,dc=org'
groupmap_superadmin = 'cn=superadmin,cn=groups,cn=accounts,dc=int,dc=example,dc=org'
```
## Enable FreeIPA Authentication {#freeipa}
After everything is set up properly you can enable FreeIPA auth in `airtime.conf`:
```
[general]
auth = LibreTime_Auth_Adaptor_FreeIpa
```
You should now be able to use your FreeIPA credentials to log in to LibreTime.

199
docs/server-config/host-configuration.md Normal file
View file

@ -0,0 +1,199 @@
---
title: Host Configuration
layout: article
category: install
---
The streaming host configuration for LibreTime is shown in the file _/etc/airtime/liquidsoap.cfg_ which is automatically generated by the **Streams** page, found on the **System** menu of the LibreTime administration interface. For this reason, you would not normally edit the streaming configuration manually, as any changes are likely to be overwritten by the administration interface.
## Database and RabbitMQ hosts {#database}
Optionally, you may wish to edit the file _/etc/airtime/airtime.conf_ to set the PostgreSQL database host, and the username and password to connect to the database with:
sudo nano /etc/airtime/airtime.conf
You can also set options for RabbitMQ messaging and the LibreTime server in this file, although you should not normally need to adjust the defaults unless you are running a large LibreTime system distributed across multiple servers. To run the LibreTime server in demo mode, which changes the greeting on the login page and prevents user accounts from being created or modified, set the value of _demo_ to 1.
[database]
host = localhost
port = 5432
name = libretime
user = libretime
password = libretime
[rabbitmq]
host = 127.0.0.1
port = 5672
user = airtime
password = XXXXXXXXXXXXXXXXXXXX
vhost = /airtime
[general]
api_key = XXXXXXXXXXXXXXXXXXXXX
web_server_user = www-data
airtime_dir = /usr/share/airtime
base_url = libretime.example.com
base_port = 80
base_dir = /
cache_ahead_hours = 1
[monit]
monit_user = guest
monit_password = airtime
[demo]
demo = 0
Save and close the file with **Ctrl+O** and **Ctrl+X**. In order to update the configuration
used by the various components of LibreTime, run the following commands
sudo systemctl restart libretime-liquidsoap
sudo systemctl restart libretime-playout
sudo systemctl restart libretime-celery
sudo systemctl restart libretime-analyzer
## API client configuration {#api}
The LibreTime API enables many types of information about the broadcast schedule and configuration to be retrieved from the LibreTime server. Other than the live-info and week-info data fetched by website widgets (see the chapter _Exporting the schedule_), all API requests must be authenticated using the secret API key stored in the file _/etc/airtime/api_client.cfg_ on the LibreTime server. This key is autogenerated during LibreTime installation and should be unique for each server.
If you intend to use the LibreTime API across a public network, for security reasons it is highly recommended that all API requests are sent over encrypted https: and that the web server is configured to accept requests to the api/ directory from specific host names or IP addresses only.
If you have changed the _base_url_, _base_port_ or _base_dir_ setting in _/etc/airtime/airtime.conf_ from the defaults, you will probably also have to update the _Hostname_ settings in the file _/etc/airtime/api_client.cfg_ accordingly.\*\*
bin_dir = /usr/lib/airtime/api_clients
api_key = 'XXXXXXXXXXXXXXXXXXXX'
api_base = api
host = libretime.example.com
base_port = 80
base_dir = /
## Apache max file size configuration {#apache}
By default, the maximum upload file size is 40 MB, which may not be large enough for some stations, especially if they are uploading prerecorded shows. The setting for this is located in _/etc/apache2/sites-available/airtime.config_. Search for and update the following in megabytes:
```
; Maximum allowed size for uploaded files.
upload_max_filesize = 40M
; Must be greater than or equal to upload_max_filesize
post_max_size = 40M
```
For quick reference, 1024 MB = 1 GB and 2048 MB = 2 GB, but most will be okay with rounding to the nearest thousand. After updating the config file, restart Apache.
```
sudo systemctl restart apache2
```
## Playout settings {#playout}
Settings for pypo, the playout engine used by LibreTime, are found in the file _/etc/airtime/airtime.conf_. After making changes to this file, you will have to issue the command:
sudo systemctl restart libretime-playout
for the changes to take effect.
############################################
# pypo - configuration #
############################################
# Set the type of client you are using.
# Currently supported types:
# 1) "obp" = Open Broadcast Platform
# 2) "airtime"
#
api_client = airtime
############################################
# Cache Directories #
# *include* trailing slash !! #
############################################
cache_dir = /var/tmp/airtime/pypo/cache/
file_dir = /var/tmp/airtime/pypo/files/
tmp_dir = /var/tmp/airtime/pypo/tmp/
############################################
# Setup Directories #
# Do *not* include trailing slash !! #
############################################
cache_base_dir = /var/tmp/airtime/pypo
bin_dir = /usr/lib/airtime/pypo
log_base_dir = /var/log/airtime
pypo_log_dir = /var/log/airtime/pypo
liquidsoap_log_dir = /var/log/airtime/pypo-liquidsoap
############################################
# Liquidsoap settings #
############################################
ls_host = 127.0.0.1
ls_port = 1234
############################################
# RabbitMQ settings #
############################################
rabbitmq_host = localhost
rabbitmq_user = airtime
rabbitmq_password = XXXXXXXXXXXXXXXXXXXX
rabbitmq_vhost = /airtime
############################################
# pypo preferences #
############################################
# Poll interval in seconds.
#
# This will rarely need to be changed because any schedule changes are
# automatically sent to pypo immediately.
#
# This is how often the poll script downloads new schedules and files from the
# server in the event that no changes are made to the schedule.
#
poll_interval = 3600# in seconds.
# Push interval in seconds.
#
# This is how often the push script checks whether it has something new to
# push to liquidsoap.
#
# It's hard to imagine a situation where this should be more than 1 second.
#
push_interval = 1# in seconds
# 'pre' or 'otf'. 'pre' cues while playlist preparation
# while 'otf' (on the fly) cues while loading into ls
# (needs the post_processor patch)
cue_style = pre
## RabbitMQ hostname changes
If the Airtime logs indicate failures to connect to the RabbitMQ server, such as:
```
2013-10-31 08:21:11,255 ERROR - [pypomessagehandler.py : main() : line
99] - Error connecting to RabbitMQ Server. Trying again in few seconds
2013-10-31 08:21:11,255 ERROR - \[pypomessagehandler.py : main() : line 99\] - Error connecting to RabbitMQ Server. Trying again in few seconds - See more at: http://forum.sourcefabric.org/discussion/16050/\#sthash.W8OJrNFm.dpuf
```
but the RabbitMQ server is running normally, this error might be due to a change in the server's hostname since Libretime installation. Directory names under _/var/lib/rabbitmq/mnesia/_ indicate that RabbitMQ's database files are organised according to the hostname of the server (ex. `rabbit@airtime`) where the hostname is _airtime.example.com_. If the hostname has changed, it may be necessary to reconfigure RabbitMQ manually, as follows:
1. Delete the files in _/var/lib/rabbitmq/mnesia/_
```
sudo rm -r /var/lib/rabbitmq/mnesia/*
```
2. Restart RabbitMQ:
```
sudo systemctl restart rabbitmq-server
```
3. Enter the following commands to set up authentication and grant permissions. The _rabbitmqctl add_user_ command requires the RabbitMQ password from the /etc/airtime/airtime.conf file as an argument. The _rabbitmqctl set_permissions_ command should be entered on one line, with the list of Airtime services repeated three times:
```
rabbitmqctl add_vhost /airtime
rabbitmqctl add_user airtime XXXXXXXXXXXXXXXXXXXX
rabbitmqctl set_permissions -p /airtime airtime
"airtime-pypo|pypo-fetch|airtime-analyzer|media-monitor"
"airtime-pypo|pypo-fetch|airtime-analyzer|media-monitor"
"airtime-pypo|pypo-fetch|airtime-analyzer|media-monitor"
```

122
docs/server-config/icecast.md Normal file
View file

@ -0,0 +1,122 @@
---
layout: article
title: Icecast Configuration
category: admin
---
## Background
LibreTime supports direct connection to two popular streaming media servers, the open source **Icecast** (<http://www.icecast.org>) and the proprietary **SHOUTcast** (<http://www.shoutcast.com>). Apart from the software license, the main difference between these two servers is that Icecast supports simultaneous MP3, AAC, Ogg Vorbis or Ogg Opus streaming from LibreTime, whereas SHOUTcast supports MP3 and AAC streams but not Ogg Vorbis or Opus. The royalty-free Ogg Vorbis format has the advantage of better sound quality than MP3 at lower bitrates, which has a direct impact on the amount of bandwidth that your station will require to serve the same number of listeners. Ogg Opus also benefits from good sound quality at low bitrates, with the added advantage of lower latency than other streaming formats. Opus is now an IETF standard (<http://tools.ietf.org/html/rfc6716>) and requires Icecast 2.4 or later to be installed on the streaming server.
Ogg Vorbis playback is supported in **Mozilla Firefox**, **Google Chrome** and **Opera** browsers, via **jPlayer** (<http://jplayer.org/>), and is also supported in several popular media players, including VideoLAN Client, also known as VLC (<http://www.videolan.org/vlc/>). (See the chapter _Stream player for your website_ on how to deliver **jPlayer** to your audience). Ogg Opus is relatively new and is supported natively in the very latest browsers, such as Mozilla Firefox 25.0, and media players including VLC 2.0.4 or later.
Streaming MP3 below a bitrate of 128kbps is not recommended for music, because of a perceptible loss of high audio frequencies in the broadcast playout. A 96kbps or 64kbps MP3 stream may be acceptable for voice broadcasts if there is a requirement for compatibility with legacy hardware playback devices which do not support Ogg Vorbis or Opus streams.
Because LibreTime supports simultaneous streaming in multiple formats, it is possible to offer one or more streams via your website, and another independent stream for direct connection from hardware players. You can test whether Ogg streams sound better at low bitrates for yourself, by using the **LISTEN** button in LibreTime's **Master Panel** to switch between streaming formats.
Conversely, you may have a music station which wants to stream at 160kbps or 192kbps to offer a quality advantage over stations streaming at 128kbps or less. Since Ogg, AAC and MP3 formats use lossy compression, listeners will only hear the benefit of higher streaming bitrates if the media files in the LibreTime storage server are encoded at an equivalent bitrate, or higher.
## UTF-8 metadata in Icecast MP3 streams
When sending metadata about your stream to an Icecast server in non-Latin alphabets, you may find that Icecast does not display the characters correctly for an MP3 stream, even though they are displayed correctly for an Ogg Vorbis stream. In the following screenshot, Russian characters are being displayed incorrectly in the _Current Song_ field for the MP3 stream:
![](/img/Screenshot223-Icecast_UTF-8_metadata.png)
The solution is to specify that the metadata for the MP3 mount point you are using should be interpreted using UTF-8 encoding. You can do this by adding the following stanza to the _/etc/icecast2/icecast.xml_ file, where _libretime.mp3_ is the name of your mount point:
<mount>
<mount-name>/libretime.mp3</mount-name>
<charset>UTF-8</charset>
</mount>
After saving the _/etc/icecast2/icecast.xml_ file, you should restart the Icecast server:
sudo invoke-rc.d icecast2 restart
Restarting icecast2: Starting icecast2
Detaching from the console
icecast2.
## Icecast handover configuration
In a typical radio station configuration, the live output from the broadcast studio and the scheduled output from LibreTime are mixed together before being sent further along the broadcast chain, to a transmitter or streaming media server on the Internet. (This may not be the case if your LibreTime server is remote from the studio, and you are using the **Show Source Mount Point** or **Master Source Mount Point** to mix live and scheduled content. See the _Stream Settings_ chapter for details).
If your **Icecast** server is hosted in a remote data centre, you may not have the option to handover the streaming media source manually, because you have no physical access to connect a broadcast mixer to the server. Disconnecting the stream and beginning another is less than ideal, because the audience's media players will also be disconnected when that happens.
The **Icecast** server has a _fallback-mount_ feature which can be used to move clients (media players used by listeners or viewers) from one source to another, as new sources become available. This makes it possible to handover from LibreTime output to a show from another source, and handover to LibreTime again once the other show has ended.
To enable fallback mounts, edit the main Icecast configuration file to define the mount points you will use, and the relationship between them.
sudo nano /etc/icecast2/icecast.xml
The example _<mount>_ section provided in the _icecast.xml_ file is commented out by default. Before or after the commented section, add three mount point definitions. The default mount point used by LibreTime is _/airtime_128_ which is shown in the _/etc/airtime/liquidsoap.cfg_ file. You must also define a mount point for the live source (called _/live.ogg_ in this example) and a mount point for the public to connect to (called _/stream.ogg_ in this example).
<mount>
<mount-name>/airtime_128</mount-name>
<hidden>0</hidden>
</mount>
<mount>
<mount-name>/live.ogg</mount-name>
<fallback-mount>/airtime_128</fallback-mount>
<fallback-override>1</fallback-override>
<hidden>0</hidden>
</mount>
<mount>
<mount-name>/stream.ogg</mount-name>
<fallback-mount>/live.ogg</fallback-mount>
<fallback-override>1</fallback-override>
<hidden>0</hidden>
</mount>
These mount point definitions mean that a client connecting to a URL such as *http://icecast.example.com:8000/stream.ogg* will first fall back to the _/live.ogg_ mount point if it is available. If not, the client will fall back in turn to the _/airtime_128_ mount point for LibreTime playout.
Setting the value of _<fallback-override>_ to 1 (enabled) means that when the _/live.ogg_ mount point becomes available again, the client will be re-connected to it. If you wish to hide the _/airtime_128_ and _/live.ogg_ mount points from the public Icecast web interface, set the value of _<hidden>_ in each of these definitions to 1.
## Source configuration
Connect the other source to the Icecast server with the same parameters defined in the _/etc/airtime/liquidsoap.cfg_ file, except for the mount point. This should one of the mount points you have defined in the _/etc/icecast2/icecast.xml_ file, such as _/live.ogg_ in the example above.
To configure **Mixxx** for streaming to Icecast, click _Options_, _Preferences_, then _Live Broadcasting_. For server _Type_, select the default of _Icecast 2_ when streaming to Debian or Ubuntu servers, as this is the current version of Icecast supplied with those GNU/Linux distributions.
![](/img/Screenshot123-Mixxx_Preferences.png)
By default, Icecast streams are buffered to guard against network problems, which causes latency for remote listeners. When monitoring the stream from a remote location, you may have to begin the live stream a few seconds before the previous stream ends to enable a smooth transition.
## Promoting your station through Icecast
If you have an Icecast server, you can put a link to the Icecast status page (by default at port 8000) on your station's homepage,
to provide an overview of available streams. See the chapter _Interface customization_ for tips on theming the
Icecast status page. You can also use Now Playing widgets (see the chapter _Exporting the schedule_) or HTML5 stream players (see the chapter _Stream player for your website_) to help grow your audience.
On an Icecast server, you can uncomment the `<directory>` section in the _/etc/icecast2/icecast.xml_ file to have
your station automatically listed on the Icecast directory website <http://dir.xiph.org> which could help you pick
up more listeners.
<!-- Uncomment this if you want directory listings -->
<directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://dir.xiph.org/cgi-bin/yp-cgi</yp-url>
</directory>
The Indymedia stream directory at <http://radio.indymedia.org/en/yp> links to grassroots independent radio projects around the world. You can add your station to their list with an additional _<directory>_ section, as follows:
<directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://radio.indymedia.org/cgi-bin/yp-cgi</yp-url>
</directory>
Another stream directory service is provided by the Liquidsoap Flows! site <http://flows.liquidsoap.fm/>. The following section can be added to the file _/usr/lib/airtime/pypo/bin/liquidsoap_scripts/ls_script.liq_ after _add_skip_command(s)_ on line 174, for a stream named '_ourstation_':
ourstation = register_flow(
radio="Rock 'n Roll Radio",
website="http://radio.example.com/",
description="Canada's most rockin' radio!",
genre="Rock",
user="",
password="",
streams=[("ogg/128k","http://streaming.example.com/libretime_128")],
ourstation)
> **Note:** For the time being, a stream can be registered on the Liquidsoap Flows! site with any username and password. Authenticated services may be offered in future.