Category Archives: Me

Using Let’s Encrypt to Secure your Slackware webserver with HTTPS

In the ‘good old days‘ where everyone was a hippy and everyone trusted the other person to do the right thing, encryption was not on the table. We used telnet to login to remote servers, we transferred files from and to FTP servers in the clear, we surfed the nascent WWW using http:// links; there were no pay-walls; and user credentials, well who’d ever heard of those, right.
Now we live in a time where every government spies on you, fake news is the new news, presidents lead their country as if it were a mobster organisation and you’ll go to jail – or worse – if your opinion does not agree with the ruling class or the verbal minority.
So naturally everybody wants – no, needs – to encrypt their communication on the public Internet nowadays.

Lucky for us, Linux is a good platform for the security minded person. All the tools you can wish for are available, for free, with ample documentation and support on how to use them. SSH secure logins, PGP encrypted emails, SSL-encrypted instant messaging, TOR clients for the darkweb, HTTPS connections to remote servers, nothing new. Bob’s your uncle. If you are a consumer.

It’s just that until not too long ago, if you wanted to provide content on a web-server and wanted to make your users’ communications secure with HTTPS, you’d have to pay a lot of money for a SSL certificate that would be accepted by all browsers. Companies like VeriSign, DigiCert, Komodo, Symantec, GeoTrust are Certificate Authorities whose root certificates ended up in all certificate bundles of Operating Systems, browsers and other tools, but these big boys want you to pay them a lot of money for their services.
You can of course use free tools (openssl) to generate SSL vertificates yourself, but these self-signed certificates are difficult to understand and accept for your users if they are primarily non-technical (“hello supportline, my browser tells me that my connection is insecure and your certificate is not trusted“).

SSL certificates for the masses

Since long I have been a supporter of CACert, an organization whose goal is to democratize the use of SSL certificates. Similar to the PGP web-of-trust, the CACert organization has created a group of ‘assurers‘ – these are the people who can create free SSL certificates. These ‘assurers’ are trusted because their identities are being verified face-to-face by showing passports and faces. Getting your assurer status means that your credentials need to be signed by people who agree that you are who you say you are. CACert organizes regular events where you can connect with assurers, and/or become one yourself.
Unfortunately, this grass-roots approach is something the big players (think Google, Mozilla) can not accept, since they do not have control over who becomes an assurer and who is able to issue certificates. Their browsers are therefore still not accepting the CACert root certificate. This is why my web site still needs to display a link to “fix the certificate warning“.
This is not manageable in the long term, even though I still hope the CACert root certificate will ultimately end up being trusted by all browsers.

So I looked at Let’s Encrypt again.
Let’s Encrypt is an organization which has been founded in 2016 by a group of institutions (Electronic Frontier Foundation, Mozilla Foundation, Michigan University, Akamai Technologies and Cisco Systems) who wanted to promote the use of encrypted web traffic by allowing everyone to create the required SSL certificates in an automated way, for free. These institutions have worked with web-browser providers to get them to accept and trust the Let’s Encrypt root certificates. And that was successful.
The result is that nowadays, Let’s Encrypt acts as a free, automated, and open Certificate Authority. You can download and use one of many client programs that are able to create and renew the necessary SSL certificates for your web servers. And all modern browsers accept and trust these certificates.

Let’s Encrypt SSL certificates have a expiration of 3 months after creation, which makes it mandatory to use some mechanism that does regular expiration checks on your server and renews the certificate in time.

I will dedicate the rest of this article to explain how you can use ‘dehydrated‘, a 3rd-party and free Let’s Encrypt client which is fully compatible with the official ‘CertBot’ client of Let’s Encrypt.
Why a 3rd-party tool and not the official client? Well, dehydrated is a simple Bash shell script, easy to read and yet fully functional. On the other hand, please have a look at the list of dependencies you’ll have to install before you can use CertBot on Slackware! That’s 17 other packages! The choice was easily made, and dehydrated is actively developed and supported.

I will show you how to download, install and configure dehydrated, how to configure your Apache web server to use a Let’s Encrypt certificate, and how to automate the renewal of your certificates. After reading the below instructions, you should be able to let people connect to your web-server using HTTPS.


Install dehydrated

The easiest way to install  dehydrated is to use the SlackBuilds.org script for it. It will install the script, create a default configuration, install a man-page and documentation.

# wget https://slackbuilds.org/slackbuilds/14.2/system/dehydrated.tar.gz
# tar xvf dehydrated.tar.gz
# cd dehydrated
# . dehydrated.info && wget $DOWNLOAD
# chmod +x dehydrated.SlackBuild
# ./dehydrated.SlackBuild
# installpkg /tmp/dehydrated-0.6.5-noarch-1_SBo.tgz

Installing the package will also create a cron job “/etc/cron.d/dehydrated” which makes dehydrated run once a day at midnight. I want that file to have some comments about what it does and I do not want to run it at midnight, so I overwrite it with a line that makes it run once a week at 21:00 instead. It will also log its activity to a logfile, “/var/log/dehydrated” in the example below:

cat <<EOT > /etc/cron.d/dehydrated
# Check for renewal of Let's Encrypt certificates once per week on Monday:
0 21 * * Mon /usr/bin/dehydrated -c >> /var/log/dehydrated 2>&1
EOT

Dehydrated uses a directory structure below “/etc/dehydrated/”.
The main configuration file you’ll find there is called “config”.
The file “domains.txt” contains the host- and domain names you want to manage SSL certificates for.
The directory “accounts” will contain your Let’s Encrypt user account and private key, once you’ve registered with them.
And a new directory “certs” will be created to store the SSL certificates you are going to create and maintain.

How to deal with these files is going to be addressed in the next paragraphs.

The dehydrated configuration files

config

The main configuration file “/etc/dehydrated/config” is well-commented, so I just show the lines that I used:

DEHYDRATED_USER=alien
DEHYDRATED_GROUP=wheel
CA="https://acme-staging-v02.api.letsencrypt.org/directory"
#CA="https://acme-v02.api.letsencrypt.org/directory"
CHALLENGETYPE="http-01"
WELLKNOWN="/usr/local/dehydrated"
PRIVATE_KEY_RENEW="no"
CONTACT_EMAIL=eric.hameleers@gmail.com
LOCKFILE="${BASEDIR}/var/lock"
HOOK=/etc/dehydrated/hook.sh

Let’s go through these parameters:

  • We are starting the ‘dehydrated script as root, via a cron job or at the commandline. The values for DEHYDRATED_USER and DEHYDRATED_GROUP are the user and group the script will switch to at startup. All activities will be done as user ‘alien’ and group ‘wheel’ and not as the user ‘root’. This is a safety measure.
  • CA: this contains the Let’s Encrypt URL for dehydrated to connect to. You’ll notice that I actually list two values for “CA” but one is commented out. The idea is that you use the ‘staging’ URL for all your tests and trials, and once you are satisfied with your setup, you switch to the URL for production usage.
    Also note that Let’s Encrypt expects clients to use the ACMEv2 protocol. The older ACMEv1 protocol will still work, but you can not register a new account using the old protocol. Its only use nowadays is to assist in migrating old setups to ACMEv2. The “CA” URL contains the protocol version number, and I highlighted that part in red.
  • CHALLENGETYPE: we will be using HTTP challenge type because that’s easiest to configure. Alternatively if you manage your own DNS domain you could let dehydrate update your DNS zone table to provide the challenge that Let’s Encrypt demands.
    What is this challenge? Let’s Encrypt’s ACME-protocol wants to verify that you are in control of your domain and/or hostname. It will try to access a verification file via a HTTP request to your webserver.
  • WELLKNOWN: this parameter defines the path component of the URL the ACME server will connect to as part of the ‘http-01’ challenge. In the case of a webserver running on our example domain “foo.net”, the URL would be  http://foo.net/.well-known/acme-challenge/m4g1C-t0k3n . The dehydrate client will have to provide that “m4g1c-t0k3n” file during certificate renewal.
    The ACME server will repeat that check for every (sub-)domain listed in your “domains.txt” file. You have to make sure that every VirtualHost configuration enables access to this location (I will show you how, below).
    Note: The first connect from the ACME server will always be over HTTP on port 80, but if your site does a redirect to HTTPS, that will work.
  • PRIVATE_KEY_RENEW: whether you want the certificate’s private key to be renewed along with the certificate itself. I chose “no” but the default is “yes”.
  • CONTACT_EMAIL: the email address which will be associated with your Let’s Encrypt account. This is where warning emails will be sent if your certificate about to expire but has not been renewed.
  • LOCK: the directory (which must be writable by our non-root user) where dehydrated will place a lock file during operation.
  • HOOK: the path to an optional script that will be invoked at various parts of dehydrate’s activities and which allows you to perform all kinds of related administrative tasks – such as restarting httpd after you have renewed its SSL certificate.

domains.txt

The file “/etc/dehydrated/domains.txt” contains the list hosts and domain names you want to associate with your SSL certificates. You need to realize that a SSL certificate contains the hostname(s) or the domain name(s) that it is going to be used for. That is why you will sometimes see a “hostname does not match server certificate” warning if you open a URL in your browser, it means that the remote server’s SSL certificate was originally meant to be used with a different hostname.

In our case, the “domains.txt” file contains just one hostname on a single line:

www.foo.net

… but that line can contain any amount of different space-separated hosts under the same domain. For instance the line could be “foo.net www.foo.net” which would tell Let’s Encrypt that the certificate is going to be used on two separate web servers: one with hostname “foo.net” and the other with the hostname “www.foo.net“. Both names will be incorporated into the certificate.

Your “/etc/dehydrated/domains.txt” file can be used to manage the certificates of multiple domains, each domain on its own line (e.g. domain foo.org on one line, and domain foo.net on another line). Each line corresponds to a different SSL certificate – e.g. for different domains. Every line can contain multiple hosts in a single domain (for instance: foo.org www.foo.org ftp.foo.org).

Directory configuration

Two directories are important for dehydrated, and we need to create and/or configure them properly.

/etc/dehydrated

First, the dehydrated configuration directory. We have configured dehydrated to run as user ‘alien’ instead of user ‘root’ so we need to ensure that the directory is writable by this user. Or better (since we installed this as a Slackware package and a package upgrade would undo an ownership change of /etc/dehydrated) let’s manually create the subdirectories “accounts” “certs”, “chains” and “var” where our user actually needs to write, and make ‘alien’ the owner:

# mkdir -p /etc/dehydrated/accounts
# chown alien:wheel /etc/dehydrated/accounts
# mkdir -p /etc/dehydrated/certs
# chown alien:wheel /etc/dehydrated/certs
# mkdir -p /etc/dehydrated/chains
# chown alien:wheel /etc/dehydrated/chains
# mkdir -p /etc/dehydrated/var
# chown alien:wheel /etc/dehydrated/var

/usr/local/dehydrated

The directory “/usr/local/dehydrated” is the location where we instructed dehydrated to store the Let’s Encrypt challenge files. They will provide proof we own the domain(s) that need a certificate.
So let’s create it and allow our non-root user to write there:

# mkdir -p /usr/local/dehydrated
# chown alien:wheel /usr/local/dehydrated

SUDO considerations

We configured the dehydrated script to drop its root privileges at startup and continue as user ‘alien’, group ‘wheel’. Because we also change the group iit is important that the sudo line for root in the file “/etc/sudoers” is changed from the default:

#root ALL=(ALL) ALL

to

root ALL=(ALL:ALL) ALL

Else you’ll get the error “Sorry, user root is not allowed to execute ‘/usr/bin/dehydrated -c’ as alien:wheel on localhost.“.

Apache configuration

Before we register an account with Let’s Encrypt and start generating certificates, let’s first create the required Apache configuration. We need to have the ‘http-01’ challenge location available, else the certificate generation will fail.

Note that if your “/etc/dehydrated/domains.txt” contains lines with multiple hosts under a domain, you’ll have to make the URL path component “/.well-known/acme-challenge” accessible through every domain host you configured. The certificate generation process will fail in case any of the required URLs cannot be validated. That is why we created “/usr/local/dehydrated/” to store the challenge file – and then we can use the Apache “Alias” directive to point there.
You can re-use this snippet of text in the <VirtualHost></VirtualHost> configuration block for every webserver host:

# We store the dehydrated info under /usr/local and use an Apache 'Alias'
# to be able to use it for multiple domains. You'd use this snippet:
Alias /.well-known/acme-challenge /usr/local/dehydrated
<Directory /usr/local/dehydrated>
    Options None
    AllowOverride None
     Require all granted
</Directory>

You can use “lynx” on the command-line to test whether a URL is valid:

$ lynx -dump http://www.foo.net/.well-known/acme-challenge/
Forbidden: You don't have permission to access /.well-known/acme-challenge/ on this server.

Despite that error, this message actually shows that the URL works (otherwise the return message would have been “Not Found: The requested URL /.well-known/acme-challenge was not found on this server.“).

Your Apache server must be enabled to accept SSL connections, and that is achieved by un-commenting this line in “/etc/httpd/httpd.conf”:

# Secure (SSL/TLS) connections
Include /etc/httpd/extra/httpd-ssl.conf

To end the Apache configuration instructions, here are the bits that define the SSL parameters for your host. Once you have executed “dehydrated -c” and obtained the certificates, add the following lines to the same <VirtualHost</VirtualHost> block as where you added the ‘Alias’ related stuff above:

SSLEngine on
SSLCertificateFile /etc/dehydrated/certs/foo.net/cert.pem
SSLCertificateKeyFile /etc/dehydrated/certs/foo.net/privkey.pem
SSLCertificateChainFile /etc/dehydrated/certs/foo.net/chain.pem
SSLCACertificatePath /etc/ssl/certs
SSLCACertificateFile /usr/share/curl/ca-bundle.crt

Running dehydrated for the first time, using the Let’s Encrypt staging server:

With all the preliminaries taken care of, we can now proceed and run ‘dehydrated’ for the first time. Remember to make it connect to the Let’s Encrypt ‘staging’ server during all your tests, to prevent their production server from getting swamped with bogus test requests!

Examining the manual page (run “man dehydrated“) we find that we need the parameter ‘–cron’, or ‘-c’, to sign/renew non-existent/changed/expiring certificates:

# /usr/bin/dehydrated -c
# INFO: Using main config file /etc/dehydrated/config
# INFO: Running /usr/bin/dehydrated as alien/wheel
# INFO: Using main config file /etc/dehydrated/config

To use dehydrated with this certificate authority you have to agree to their terms of service which you can find here: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf

To accept these terms of service run `/usr/bin/dehydrated --register --accept-terms`.

What did we learn here?
In order to use dehydrated, you’ll have to register first. Let’s create your account and generate your private key!

Do not forget to set the “CA” value in /etc/dehydrated/config to a URL supporting ACMEv2. If you use the old staging server URL you’ll see this error: “Account creation on ACMEv1 is disabled. Please upgrade your ACME client to a version that supports ACMEv2 / RFC 8555. See https://community.letsencrypt.org/t/end-of-life-plan-for-acmev1/88430 for details.

With the proper CA value configured (you’ll have to do this both for the staging and for the production server URL) , you’ll see this if you run “/usr/bin/dehydrated –register –accept-terms”:

# /usr/bin/dehydrated --register --accept-terms
# INFO: Using main config file /etc/dehydrated/config
# INFO: Running /usr/bin/dehydrated as alien/wheel
# INFO: Using main config file /etc/dehydrated/config
+ Generating account key...
+ Registering account key with ACME server...
+ Fetching account ID...
+ Done!

Generate a test certificate

We’re  ready to roll. As said before, it is proper etiquette to run all your tests against the Let’s Encrypt ‘staging’ server and use their production server only for the real certificates you’re going to deploy.
Let’s run the command which is also being used in our weekly cron job, “/usr/bin/dehydrated -c”:

# /usr/bin/dehydrated -c
# INFO: Using main config file /etc/dehydrated/config
# INFO: Running /usr/bin/dehydrated as alien/wheel
# INFO: Using main config file /etc/dehydrated/config
+ Creating chain cache directory /etc/dehydrated/chains
Processing www.foo.net
+ Creating new directory /etc/dehydrated/certs/www.foo.net ...
+ Signing domains...
+ Generating private key...
+ Generating signing request...
+ Requesting new certificate order from CA...
+ Received 1 authorizations URLs from the CA
+ Handling authorization for www.foo.net
+ Found valid authorization for www.foo.net
+ 0 pending challenge(s)
+ Requesting certificate...
+ Checking certificate...
+ Done!
+ Creating fullchain.pem...
+ Done!

This works! You can check your web site now if you did not forget to add the SSL lines to your VirtualHost block; your browser will complain that it is getting served an un-trusted SSL certificate issued by “Fake LE Intermediate X1“.

Generate a production certificate

First, change the “CA” variable in “/etc/dehydrated/config” to the production CA URL “https://acme-v02.api.letsencrypt.org/directory”.
Remove the fake certificates that were created in the previous testing step so that we can create real certificates next:

# rm -r /etc/dehydrated/certs/www.foo.net

Now that we’ve cleaned out the fake certificates, we’ll generate real ones:

# /usr/bin/dehydrated -c
# INFO: Using main config file /etc/dehydrated/config
# INFO: Running /usr/bin/dehydrated as alien/wheel
# INFO: Using main config file /etc/dehydrated/config
Processing www.foo.net
+ Creating new directory /etc/dehydrated/certs/www.foo.net ...
+ Signing domains...
+ Generating private key...
+ Generating signing request...
+ Requesting new certificate order from CA...
+ Received 1 authorizations URLs from the CA
+ Handling authorization for www.foo.net
+ 1 pending challenge(s)
+ Deploying challenge tokens...
+ Responding to challenge for www.foo.net authorization...
+ Challenge is valid!
+ Cleaning challenge tokens...
+ Requesting certificate...
+ Checking certificate...
+ Done!
+ Creating fullchain.pem...
+ Done!

If you reload the Apache server configuration (using the command “apachectl -k graceful”) you’ll now see that your SSL certificate has been signed by “Let’s Encrypt Authority X3” and it is trusted by your browser. We did it!

Automatically reloading Apache config after cert renewal

When your weekly cron job decides that it is time to renew your certificate, we want the dehydrated script (which runs as a non-root account) to reload the Apache configuration. And of course, only root is allowed to do so.

We’ll need a bit of sudo magic to make it possible for the non-root account to run the “apachectl” program. Instead of editing the main file “/etc/sudoers” with the command “visudo” we create a new file “httpd_reload” especially for this occasion, in sub-directory “/etc/sudoers.d/” as follows:

# cat <<EOT > /etc/sudoers.d/httpd_reload
alien ALL=NOPASSWD: /usr/sbin/apachectl -k graceful
EOT

This sudo configuration allows user ‘alien’ to run the exact command “sudo /usr/sbin/apachectl -k graceful” with root privileges.

Next, we need to instruct the dehydrated  script to automatically run “sudo /usr/bin/apachectl -k graceful” after it has renewed any of our certificates. That is where the “HOOK” parameter in “/etc/dehydrated/config” comes to play.

As the hook script, we are going to use dehydrated’s own sample “hook.sh” script that can be downloaded from https://raw.githubusercontent.com/lukas2511/dehydrated/master/docs/examples/hook.sh or (if you used the SlackBuilds.org script to create a package) use “/usr/doc/dehydrated-*/examples/hook.sh”.

# cp -i /usr/doc/dehydrated-*/examples/hook.sh /etc/dehydrated/
chmod +x /etc/dehydrated/hook.sh

This shell script contains a number of functions, each is relevant and will be called at a certain stage of the certificate renewal process. The dehydrated script will provide several environment variables to allow a high degree of customization, and all of that is properly documented in the sample script, but we do not need any of that. Just at the end of the “deploy_cert()” function we need to add a few lines:

deploy_cert() {
# ...
# After successfully renewing our Apache certs, the non-root user 'alien'
# uses 'sudo' to reload the Apache configuration:
sudo /usr/sbin/apachectl -k graceful
}

That’s all. Next time dehydrated renews a certificate, the hook script will be called and that will reload the Apache configuration at the appropriate moment, making the new certificate available to visitors of your web site.

Summarizing

I am glad you made it all the way down here! In my usual writing style, the article is quite verbose and gives all kinds of contextual information. Sometimes that makes it difficult for the “don’t bother me with knowledge, just show me the text I should copy/paste ” user but I do not care for that.

I do hope you found this article interesting, and useful. If you spotted any falsehoods,let me know in the comments section below. If some part needs more clarification, just tell me.

Have fun with a secure web!

Eric

(more…)

How to access your e-books online

In a previous article about the Calibre e-book library management program, I wrote that I did away with USB cable connections to transfer e-books from my Calibre library to my E-reader. Instead, I made my e-book library accessible on-line and now I am able to download my books securely over the Internet – no matter where I am, as long as I have a network connection.

In this article today, I am going to explain how I make my Calibre library accessible on-line.

Understandably, the article will be Slackware-centric, because that is where I have my Calibre library and where I run all the programs that I need. But, the technology and the configuration is generic enough that readers of this article running another distro or even employing an embedded (ARM) device will be able to make it work.

Which software is used?

Apache and PHP are standard part of Slackware Linux. I assume that you know how to setup an Apache web server. The good news is that Slackware’s default httpd configuration works out of the box. However, it does not enable a secure (https) web site. That part is on you.
If your content server is going to be used in your home network only, then HTTPS is not even needed.
I have a package for Calibre in my repository which of course you will definitely need if you want to build an e-book library.
You’ll have to download the ZIP file of the latest COPS release from https://github.com/seblucas/cops/releases – the ZIP contains the extra stuff that is not contained in the source .tar.gz file.
The remainder is just configuration.

Now let me explain my setup.

The Calibre library

It all starts with Calibre of course. It is a desktop program, available for Linux, Windows and MacOS. It stores your e-book library as a directory tree.  The directories immediately below the root of the tree are the book authors. In the root of the directory tree, Calibre creates a SQLite database file containing all the library metadata. The simple directory structure and the SQLite database file make that a Calibre library is independent of the Operating System that Calibre runs on. Its database scheme can be updated between major releases though. From within the Calibre GUI, it is however trivial to re-create this database file from scratch if it becomes corrupted.
This simple library setup has the advantage that if you store the library on a Cloud service like Dropbox, you can have access to your library from multiple computers running different Operating Systems (but preferably all the same version of Calibre). As long as one person accesses the library at any time, the Calibre database file will not get corrupted. This is how I have setup Calibre for my wife so that she can manage her e-books from every computer in the house.

Where to create the library

Myself, I use Calibre on a Linux machine which runs 24/7 (my package-build server in fact). I run a XFCE graphical desktop session inside a VNC server and that allows me to work in a desktop environment that’s always there for me. I use NoVNC to access this desktop using a web browser and that is perfect for corporate envronments which put a firewall up for everything except HTTPS traffic. Perhaps I’ll write another article sometime, explaining how to set that up.

What matters is that the Calibre library is stored on a machine with Internet access, and that this computer is running a web server like Apache. In Slackware, Apache httpd is the default webserver program.
I made this web server accessible from the Internet by configuring my ISP’s Internet router to forward ports 80 (http) and 443 (https) to the internal IP address of my Slackware machine.
For the sake of this article, let’s assume that two separate Calibre libraries exist on this computer, mine is located in /data/Calibre/EricLibrary and my wife’s books are stored in /data/Calibre/WifeLibrary . In Calibre itself, you can easily switch between libraries so that me and my wife are both able to maintain a separate collection of books. Our book tastes have no overlap…

How to configure the web server

I want both libraries to be accessible online.
I do not want to use Calibre’s own content server but instead use COPS. COPS is a collection of PHP scripts, and it does not require the Calibre program to function. It just needs access to the physical directory containing your Calibre library and it understands the Calibre SQLite database format.
If you want to get creative, you can install COPS on an Internet server – e.g. if you do not have a webserver at home. In that case, use a cloud storage service like Dropbox to keep your library in sync between your computer at home and that remote server running Apache.

My example setup is a Slackware computer at home with Apache enabled:

# chmod +x /etc/rc.d/rc.httpd
# /etc/rc.d/rc.httpd start

Apache uses the concept of a DocumentRoot, which is a directory accessible by the httpd server. Everything stored below that DirectoryRoot will be accessible via the URL of the webserver. Never store files below the DocumentRoot that you do not want to share!
I downloaded and extracted the COPS zip file directly into the Apache DocumentRoot directory (the default in Slackware is configured in the file ‘/etc/httpd/httpd.conf’ to be “/srv/httpd/htdocs/” but you can change that default location of course):

# cd /tmp
# links https://github.com/seblucas/cops/releases/download/1.1.3/cops-1.1.3.zip
# cd /srv/httpd/htdocs/
# unzip /tmp/cops-1.1.3.zip
# ln -s cops-1.1.3 mybooks
# cd mybooks
# cat <<EOT > config_local.php
$config = array();
$config['calibre_directory'] = array ("Eric" => "/data/Calibre/EricLibrary/", "Wife => "/data/Calibre/WifeLibrary/");
$config['cops_title_default'] = "Aliens Library";
$config['cops_use_url_rewriting'] = "1";
$config['cops_recentbooks_limit'] = '100';
$config['cops_update_epub-metadata'] = "1";
$config['cops_books_filter'] = array ("Books" => "!News");
EOT

The lines from the “cat << EOT” until the “EOT” on its own line is called a “here document“. You can copy/paste these lines into a terminal and it will create the file “config_local.php” with the content as shown between the “EOT” lines.
This is a configuration which allows access to two separate libraries. If you access the “recently added” section of a library it will show the latest 100 books instead of the default 20 books. It does some URL re-writing to generate cleaner URLs and it will not show any News sources (in Calibre, you can add various paid-for and free newspaper subscriptions and those will then be dpwnloaded daily, but I do not want to see those online).
Compare this configuration of mine to the ‘config_local.php.example’ file in the COPS directory. The above is not all you can configure, although it is sufficient. All configurable parameters are documented in ‘config_default.php’ which also defines their default values.

You’ll have noticed that I created a symlink to the extracted cops files, which allows me to use an easy to remember URL to access my books. Suppose my apache server is accessible as http://foo.net/ – then my COPS installation will be accessible at http://foo.net/mybooks/ .

That’s all!

Under the above ‘mybooks’ URL you will now find a COPS installation with two Calibre libraries with separate names “Eric” and “Wife”. Pick a nice template and theme, and try out the ebook-reader which is part of COPS (you  can read EPUBs in a web browser, no E-reader required).

Accessing COPS through the OPDS protocol

You want to configure your E-reader to access the library. An E-reader which contains a webbrowser is easy, just open http://foo.net/mybooks/ and click a book to download it.
Other E-readers, like FBReader for Android, are able to connect to an OPDS (Open Publication Distribution System) catalog. The COPS program exposes your library as a OPDS catalog if you just add ‘feed.php’ to the URL.
I.e. enter http://foo.net/mybooks/feed.php into the Network Library menu of FBReader and you’ll get instant access to “Alien’s Library” where you can browse Authors, Series, Categories, Recent Additions and read book descriptions, and then download the books you want to read.
If you want to always start with a list of recent library additions, you  can add ‘?page=10’ at the end of the URL so that it becomes http://foo.net/mybooks/feed.php?page=10

Hiding the cops files from the Apache DocumentRoot

Some people feel a bit anxious having these cops files accessible in their DocumentRoot – suppose someone gains access to them trough other means. You can use Apache’s “Alias” directive to install COPS in e.g. /usr/local instead. In that case, add the following lines to your /etc/httpd/httpd.conf or whatever file holds your website definition:

    <Directory "/usr/local/cops-1.1.3/">
        AllowOverride All
        Options +ExecCGI +FollowSymLinks
        Require all granted
    </Directory>
    Alias /mybooks/ /usr/local/cops-1.1.3/

You should check the validity of your httpd configuration before restarting the webserver:

# apachectl configtest
# /etc/rc.d/rc.httpd restart

And the URL to access your library will remain the same, i.e. http://foo.net/mybooks/feed.php?page=10 , only in this case your actual DocumentRoot directory will be empty.

Adding some sense of security

After following the above instructions, you now have an e-book library online whose access is not restricted in any way. If some search engine passes by it will neatly catalog all your books for other people to find. Oops!

You’ll need a basic access restriction at least. Apache offers a ‘Basic Authentication’ setup which will prompt anyone who tries to access your library for a valid account and password.
To achieve this, let’s first create a password file containing the account/password combinations for the people you want to grant access. For the sake of this example, I will grant myself and my wife access by creating account/password combinations for us in a file which we will then use in  our Apache configuration.
The first ‘htpasswd’ command below has an additional ‘-c’ parameter to create the file “/etc/httpd/passwords/htaccess.opds”:

# mkdir -p /etc/httpd/passwords/
# htpasswd -b -c /etc/httpd/passwords/htaccess.opds eric ericspassword
# htpasswd -b /etc/httpd/passwords/htaccess.opds wife wifespassword

The file will then have these contents, you see that the passwords are now MD5 encrypted:

eric:$apr1$OtKDA27W$l2ac4DAhGCG53igy6jT5A/
wife:$apr1$Zql/HEUC$wrNckoe57YPC0u2w8mL/M0

Read “man htpasswd” to find out more about this command and its parameters.

Next you need to change the Apache <Directory></Directory> block which I provided above. It will become like this:

    <Directory "/usr/local/cops-1.1.3/">
        AllowOverride All
        Options +ExecCGI +FollowSymLinks
        AuthBasicAuthoritative off
        AuthUserFile /etc/httpd/passwords/htaccess.opds
        AuthType Basic
        AuthName "OPDS Server"
        Require valid-user
        # Require all granted
    </Directory>
    Alias /mybooks/ /usr/local/cops-1.1.3/

Once you made these changes, validate the configuration and restart the webserver:

# apachectl configtest
# /etc/rc.d/rc.httpd restart

Now you will be greeted by an authentication request, next time you access your library. Only those users whose username/password combinations are stored in “/etc/httpd/passwords/htaccess.opds” will be able to get access.

Using encrypted HTTP

You should realize that these passwords will still be transmitted in cleartext if your webserver is not using HTTPS. It is possible for people to sniff the network connection and find your credentials.

I think however that instructions about enabling HTTPS for your Apache belongs in another blog post. Let me know in the comments section below if you have a need for such an article.
Also, let me know if parts of the above instructions are too cryptic and I will update the text where needed.

Good luck! Eric

Reverse birthday present: KDE-5_19.05

After a three-month hiatus, I have new Plasma5 packages for you. I just uploaded “KDE-5_19.05” to the ‘ktown‘ repository. It’s filled to the brim with new stuff.
Hopefully not many of you will be disappointed by the fact that this is a 64bit-only release. I have a severely limited capacity unfortunately due to health issues. But, today is my birthday and I wanted to get this out as a ‘reverse present’ to all of you 🙂 The 32bit packages will eventually follow, but I am afraid I will no longer be able to manage a monthly update cycle.

As always, these packages are meant to be installed on a full installation of Slackware-current which has had its KDE4 removed first. These packages will not work on Slackware 14.2.

What’s new for this May 2019 release

My May 2019 release of KDE Plasma5 for Slackware contains the KDE Frameworks 5.58.0, Plasma 5.15.5 and Applications 19.04.1. All this on top of Qt 5.12.3.

Deps:
Because of the three-month hiatus between releases, there are quite some updates to be reported. The ‘qt5’ package went up to 5.12.3 and with it come the latest versions of ‘libxkbcommon’, ‘qt5-speech’, ‘qca-qt5′, gpgme’, ‘sip’ and ‘PyQt5’. The ‘qt5-webkit’ package was recompiled against the new ‘qt5’.

The ‘cryfs’ package and its dependency ‘cryptopp’ were updated to their most recent releases.
To support the latest version of kdenlive, a new package ‘rttr’ was added and the ‘mlt’ package was updated.

Frameworks:
Frameworks 5.58.0 is an incremental stability release, see: https://www.kde.org/announcements/kde-frameworks-5.58.0.php

Plasma:
Plasma 5.15.5 is the final iteration before we move on to 5.16. See https://www.kde.org/announcements/plasma-5.15.5.php

Plasma-extra:
I updated to the latest release of ‘kdeconnect-framework’. If you use a smartphone then this is a must-have application to integrate phone and laptop into one seamless experience.

Applications;
Applications 19.04.1 is a stability and bugfix update for the 19.04 cycle, but since I never packaged the .0 release, this is actually the first ‘ktown for Slackware‘ release with the new Applications in which we find a KDEnlive with 60% of its code re-written from scratch. Other main applications like Okular, Dolphin, Kate have been enhanced significantly. See https://www.kde.org/announcements/announce-applications-19.04.1.php and if you want more detail about the 19.04 cycle you should also read https://www.kde.org/announcements/announce-applications-19.04.0.php .

Applications-extra:
Many upgrades here: ‘alkimia’, ‘digikam’, ‘falkon’, ‘kdevelop’, ‘kdev-php’, ‘kdev-python’, ‘kmymoney’, ‘kpmcore’, ‘krita’, ‘kstars’, ‘okteta’ and ‘partitionmanager’.

Where to get it

Download the KDE-5_19.05 from the usual location at https://slackware.nl/alien-kde/current/latest/ . Check out the README file in the root of the repository for detailed installation or upgrade instructions.

I am not yet able to generate a new ISO of the Slackware Live Plasma5 Edition, because I am in the midst of an update to the liveslak scripts. When I find time to finish or revert that update, the ISO will follow soon after. When I upload a new Plasma5 Live ISO you will find it in https://slackware.nl/slackware-live/latest/

And let me know – in the comments section below – whether you are actually using my 32bit Plasma5 packages!

Have fun! Eric

Explorations into the world of electronic music production

Apart from playing the recorder flute in primary school and keyboard with my father-in-law, I pretty much never had the chance to make music or even, to create new music. That did not bother me in the past, but when I married into a very musical and creative family I realized I was the only one without musical education or skill in playing an instrument. The family has (ir)regular jam sessions and sometimes arranges (mostly private but) quite high-quality classical music performances.

But, I had other hobbies, Slackware being one of them of course, and reading books while listening to my own music collection (which almost has no overlap with my wife’s by the way). And I was glad when I saw that my son has inherited my wife’s genes and has a knack for languages and music. He is exploring digital music making, has a keyboard or two and installed Ableton Live on his computer. I could never convince him that Slackware was the better alternative to Windows, all his friends are on Windows and what the group does is important for a teen. And furthermore, there’s a slew on tutorial and instruction video’s out there, all expecting you to use Ableton.

I looked at Ableton for its possibilities, and I had several discussions with one of my colleague/friends who is also a DJ/producer and uses Ableton a his primary driver. Seems to be a real nice program… but it costs hundreds of euros. So purchasing a license for Windows 10 and another one for Ableton, just to be able to converse with my son was not an option. I’ll introduce him to my friend and we’ll visit his studio to get inspiration. Then he can implement what he learnt, using tools he is familiar with.

During the past two years, I made some purchases just to have fun with creating sounds and rhythms, buying a couple of Pocket Operators from Teenage Engineering. I had one of these PO’s in my car, plugged into the car stereo and let my son create loops and sounds while on trips. Lots of fun and not too expensive. I also have an external USB soundcard,a FocusRite Scarlett 2i4. and a MIDI keyboard and bass guitar in the attic. But life’s too short and lots of stuff asks for attention – I never spent much productive time with my gear.

But these recent discussions about how to create digital music from scratch, and my wish toe be able to record the live performances of my in-laws, triggered a desire to have a better look at electronic music production and music recording, but then on Slackware Linux of course.

What would be needed for that? I would need software to create sounds (i.e. synthesizers), manipulate audio, create drum tracks, sequence the music, record and mix it. Also my USB sound card needs to be supported and I want my use midi keyboard to enter the notes that I play into the system. I obviously need low-latency real-time performance of my Digital Audio Workstation (DAW).

I guess that for many Linux musicians, the Debian-based AVLinux is a first choice when looking for pre-packaged, pre-configured Digital Audio Workstation (DAW) solutions and supporting software. But we Slackers already have Studioware – a Slackware expansion set which gives you a great toolkit with audio- and video manipulation software. My liveslak project even supports Studioware directly, and is able to create a Studioware Live ISO. You should try that out – it has a ton of software, not just for audio but also for video recording, manipulation and recording.

But… again… and that’s just me… I think that there’s no fun in using other people’s ready-made stuff. Here I am thinking again as the software packaging geek who wants to create possibilities for other people while not necessarily using those myself.

Anyway, I decided not to look too closely at what others had already done, and research a decent set of software products that I want to try out, and on Slackware-current too. Studioware is running on Slackware 14.2 and I tend to develop new stuff on our development platform.

And after a couple of weeks spent on reading, compiling, testing and scratching my head at my lack of knowledge, I came up with this list of software that I think is a nice start for venturing into DAW country. All of this is free and open source:

  • Music recording/mixing/manipulating:
    • ardour: the professional-grade Digital Audio Workstation (DAW).
  • Sound editing:
    • audacity: a graphical sound editor with a GTK3 based UI.
  • Synthesizers:
    • amsynth: an analog modelling synthesizer.
    • helm: a polyphonic synth with lots of modulation also works as a LV2 plugin.
    • zynaddsubfx: a software synthesizer and also a LV2 plugin.
  • Drum machine:
    • hydrogen: an advanced drum machine with Qt5 based GUI.
  • MIDI input:
    • vmpk: Virtual MIDI Piano Keyboard is a MIDI events generator and receiver which can be used to drive a MIDI synthesizer.
  • Audio manipulation plugins (not counting the standalone applications mentioned above that will also run as an Ardour plugin):
    • avldrums.lv2: a LV2 plugin wrapping the AVLinux Drumkits.
    • calf: Calf Studio Gear is a LV2/DSSI plugin collection but it also works as a standalone JACK-host.
    • eq10q: equalizer (and more) as LV2-plugins.
    • vamp-aubio-plugins: a small collection of audio feature extraction plugins.
  • System tools:
    • jack-audio-connection-kit (jack2): to provide low-latency real-time audio routing.
    • alsa-plugins-jack: part of alsa-plugins but not included in Slackware, allows audio to be routed to and from ALSA applications that are not JACK-aware.
    • qjackctl: a Qt5 application to control the JACK sound server.
  • Support libraries for implementing a DAW:
    • aubio: a system to extract annotations from audio signals.
    • ladspa_sdk:  SDK for sound plugins adhering to the Linux Audio Developer’s Simple Plugin API (LADSPA).
    • liblo: implementation of the Open Sound Control (OSC), a protocol for communication among multimedia devices.
    • lv2: the LV2 open standard for audio plugins.
    • rubberband: a library for audio time-stretching and pitch-shifting.
    • vamp-plugin-sdk: an audio processing plugin system (you still need to install actual plugins).
    • wxGTK3: GTK+3 implementation of the cross-platform wxWidgets API
  • Further dependencies for the above (not part of Slackware) that I had to create as packages to get it all working:
    • drumstick: MIDI libraries for Qt5. This is also part of my ‘ktown‘ Plasma5 desktop package set.
    • liblrdf: library to access LADSPA plugin metadata.
    • lilv: a library for using LV2 plugins in applications.
    • mxml: library to read and write XML and XML-like data files.
    • serd: RDF syntax library.
    • sord: library for storing RDF data in memory.
    • sratom: library for serialising LV2 atoms to and from RDF.
    • suil: library for loading and wrapping LV2 plugin UIs.
  • System libraries that I already had in my repositories and which you may already have installed:
    • qt5: the toolkit for creating graphical interfaces
    • libxkbcommon: support library for Qt5, handling keyboard descriptions.
    • OpenAL: support library for Qt5, implementing a 3D audio API.
    • SDL_sound: support library for Qt5 handling the decoding of various sound file formats.
Update 15-march-2019

Additions to the above set resulting from the discussion in the comments area below the main article:

  • Music notation:
  • Live Coding:
    • supercollider: a platform for audio synthesis and algorithmic composition
  • Plugins:
    • lsp-plugins: Linux Studio Plugins supporting LV2, LADSPA and Jack.
  • Support libraries:
    • portaudio: a cross platform audio I/O library.
    • portmidi: a platform independent library for MIDI I/O.
  • Front-ends:
    • qsynth: a Qt5 GUI Interface for FluidSynth.

Looking back, that is a big list! Actually when I started with my shortlist as mentioned above I did not anticipate that my ideas would require this many tools to support it. However I think that in order to do some serious audio production work on your computer, this is actually the minimum of applications that you require. There may be more, and I am very curious to hear from you if there is Open Source Software not on the above list, which you think is invaluable to your work as a musician or music producer and should be added here.

The ‘big boy’ in this collection, and the center of any DAW activities on Linux, is Ardour.

Ardour DAW

This is a complex program, but luckily the developers have an extensive manual online. And if you search on Youtube you will find a lot of videos on how to work in Ardour (most of them for older versions and most of them too obscure or too rambling to be educational). However, an Ardour channel on Youtube has just been created with the intention of releasing a new series of quality instruction videos, produced by Unfa who himself has a lot of nice videos on his own channel. Like I said, I have been scratching my head a lot lately, but my hair is still there and I will make progress and understand how to use this tool efficiently… eventually.
And I am glad to finally have Audacity in my repository, something I wanted/needed for quite a while.

All these packages are available in my regular repository, with one caveat (at least for now): I have built all of them for Slackware-current (both 32bit and 64bit). If you are running Slackware 14.2 then for now you need to have a good look at Studioware instead, or you can of course download the sources for my packages and compile them yourself.
The build order is roughly like this:

  • jack2
  • alsa-plugins-jack (depends on jack2)
  • lv2
  • vamp-plugin-sdk
  • aubio (depends on jack2, and additionally on ffmpeg on Slackware 14.2)
  • liblo
  • ladspa_sdk
  • liblrdf (depends on ladspa_sdk)
  • rubberband (depends on ladspa_sdk and vamp-plugin-sdk)
  • serd
  • sord (depends on serd)
  • sratom (depends on lv2 and sord)
  • lilv (depends on sratom)
  • suil (depends on lv2 and qt5)
  • ardour (depends on jack2 aubio lv2 vamp-plugin-sdk liblo liblrdf lilv rubberband and suil)
  • mxml
  • ntk
  • portmidi (depends on openjre)
  • portaudio (depends on jack2)
  • zynaddsubfx (depends on jack2 liblo mxml ntk and portaudio)
  • hydrogen (depends on jack2 ladspa_sdk liblo liblrdf rubberband and qt5)
  • wxGTK3
  • audacity (depends on jack2 ladspa_sdk lilv suil vamp-plugin-sdk and wxGTK3)
  • qjackctl (depends on jack2 and qt5)
  • calf (depends on jack2 and lv2, and for Slackware 14.2 additionally on fluidsynth)
  • avldrums.lv2 (depends on lv2)
  • helm (depends on jack2 and lv2)
  • amsynth (depends on jack2 ladspa_sdk and liblo)
  • eq10q (depends on lv2)
  • vamp-aubio-plugins (depends on aubio and vamp-plugin-sdk)
  • drumstick (depends on qt5)
  • vmpk (depends on drumstick)
  • musescore (depends on jack2 portaudio portmidi and qt5)
  • qsynth (depends on qt5)
  • lsp-plugins (depends on jack2 ladspa and lv2)
  • supercollider (depends on jack2 and qt5)

I hope to get some interesting feedback from you. I am also considering how all of this could be added to a function-focused liveslak variant, as small as possible so it may load completely into memory. Actually I would prefer to attempt such a Live ISO using a bare Plasma5, rather than XFCE or other light-weight desktop environments (everybody else is probably already using XFCE). The Plasma5 desktop framework is very powerful and fast, and it could benefit the user of a DAW if everything she plugs in just works.

Ideas? Enjoy! Eric