SaruWiki - User contributions [en]

Main Page

2021-09-23T15:06:31Z

Saruman!:

<big>'''Welcome to SaruWiki.'''</big>

This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users.

Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software.

<big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are.

----
<big>'''Main Content'''</big>

* Setting up a [[Debian Jessie base server|Debian 8 Jessie base server]] is a howto on the installation of a very basic Linux box under Jessie (it's actually not even a server yet).
* Using ''md'' and ''btrfs'' for [[software-based RAID]] contains our ideas and observations on data redundancy.
* The use of [[APT and aptitude]] is crucial to the concept of a Debian machine.
* [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it.
* [[Essential system software]] lists all (sets of) packages that we deem, well, essential.
* The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots.
* The [[networking section]] treats subjects like setting persistent routes.
* The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling.
* The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel.
* [[Hardware monitoring]] is important for your server's health and reliability.
* Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]].
* Creating a [[backup]] for your server.

'''Authentication and security'''
* [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it.
* [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository.
* [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them

'''Your own LAMP server'''
* [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]].
* [[Database 101]] introduces you to MySQL.

'''Other server apps'''
* The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend.
* [[Add an X11 server]] to your server, if you need one.
* Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP.
* The [[Asterisk section]] is about all things re: telephony on Debian Lenny.
* [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box.
* How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now.
* How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"])
* How to create [[your own ownCloud]] server (and here's [http://www.thecomputerkid.com/2013/06/why-you-should-use-owncloud.html why] you should do this)

----
If you'd like to create a new page, please log in and go ahead
'''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team.

Certificate fundamentals

2016-10-29T20:25:09Z

Saruman!: /* We've got the CA certificate, now what? */

==Certificates, an introduction==
Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates.

Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera).

Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business.

==Creating the Certificate Authority (CA) - preparations==
To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters.

===Deciding on CA parameters===
'''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]).

How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days.

'''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key.

How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-)

'''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values:
* Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here.
* Country: NL (that's the Netherlands)
* Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it.
Maybe you want to provide more default information to your CA setup; just look further down on how to.

So the information we've decided upon is like this:
{| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5"
!style="background:#ffdead;"|Parameter
!style="background:#ffdead;"|value
|-
|root certificate encryption
|4096 bits
|-
|root certificate validity
|5479 days (15 years)
|-
|certificate store
|''/etc/ssl/ca''
|-
|default certificate validity
|370 days (1 year)
|-
|Organization name
|Saruman.biz
|-
|Certificate province/county name (default)
|Utrecht
|-
|Certificate country name (default)
|NL
|-
|}

=== Editing the ''openssl.cnf'' configuration file===
When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big <enter> key.

First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits.

Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded.

So the changes we've made will amount to something like this:
[ CA_default ]
dir = /etc/ssl/ca
...
default_days = 370
...
[ req ]
default_bits = 2048
...
[ req_distinguished_name ]
0.organizationName_default = Saruman.biz
stateOrProvinceName_default = Utrecht
countryName_default = NL
Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want.

=== Editing the ''CA.sh'' script ===
Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts.

We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''.

With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this:

DAYS="-days 370" # 1 year
CADAYS="-days 5479" # 15 years
...
echo "Making CA certificate ..."
$REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \
-out ${CATOP}/$CAREQ

==the Certificate Authority root certificate==
Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair".

===Creating the CA root certificate key pair===
To generate the CA's public and private root certificate, as root, execute
/usr/lib/ssl/misc/CA.sh -newca
With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit <enter>.

Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).

For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves. 
Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/ssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key.

The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/ssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/ssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''.

So now we've got two root certificates, namely
* '''private''' key ''/etc/ssl/ca/private/cakey.pem'', and
* '''public''' key ''/etc/ssl/ca/cacert.pem''.
NEVER send your private key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here).

You can inspect your certificates (when you're in directory ''/etc/ssl/ca'') with commands like this:
openssl x509 -in cacert.pem -noout -text
openssl x509 -in cacert.pem -noout -dates
openssl x509 -in cacert.pem -noout -purpose
Note from the last command above, that this certificate is obviously a root certificate: it can verify the signature of everything but the kitchen sink.

In the same manner you can inspect your private key - note that you'll have to provide the passphrase to complete this command:
openssl rsa -in private/cakey.pem -noout -text

Note that this can be used to check if the private key and certificate belong together: the `modulus' and the `public exponent' portions in the private
key and the certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach:
openssl x509 -in cacert.pem -noout -modulus | openssl md5
openssl rsa -in private/cakey.pem -noout -modulus | openssl md5
And then compare these really shorter numbers (and again, you'll have to provide the passphrase to read the private key). Both commands will output something like:
(stdin)= 96a281eca852b794a907186a9703ddf4
With overwhelming probability they will differ if the keys are different.

===We've got the CA certificate, now what?===
With the root CA certificates available to us, we've got the following things to do:
* guard very carefully the public and (especially) the private key file;
* sign certificates for our own use;
* distribute the public CA certificate to every machine/person that may need to verify certificates that we've signed.
The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. At the very least, you have to make sure the private key is owned by root or an administrative account, and is ''not'' world-readable. It might even be wise to remove the private key altogether, and keep it on a USB stick, and only read it when signing certificates.

The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section.

The last point means we need to send out our public CA certificate. In some cases, you can provide others with your ''.pem'' file, but in other cases you're better off providing a simpler ''.crt'' file. The difference is explained nicely at the [http://info.ssl.com/article.aspx?id=12149 ssl.com site]
To create a public CA certificate in .crt format you can issue the following command:
openssl x509 -outform der -in cacert.pem -out cacert.crt
By the way, it's usually better to distribute the public certificate with a more recognizable file name, such as ''saruman.bizRootCA.crt''

Certificate fundamentals

2016-10-29T20:23:57Z

Saruman!: /* Creating the CA root certificate key pair */ added passphrase

Certificate fundamentals

2016-10-29T20:21:48Z

Saruman!: /* We've got the CA certificate, now what? */

==Certificates, an introduction==
Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates.

Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera).

Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business.

==Creating the Certificate Authority (CA) - preparations==
To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters.

===Deciding on CA parameters===
'''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]).

How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days.

'''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key.

How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-)

'''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values:
* Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here.
* Country: NL (that's the Netherlands)
* Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it.
Maybe you want to provide more default information to your CA setup; just look further down on how to.

So the information we've decided upon is like this:
{| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5"
!style="background:#ffdead;"|Parameter
!style="background:#ffdead;"|value
|-
|root certificate encryption
|4096 bits
|-
|root certificate validity
|5479 days (15 years)
|-
|certificate store
|''/etc/ssl/ca''
|-
|default certificate validity
|370 days (1 year)
|-
|Organization name
|Saruman.biz
|-
|Certificate province/county name (default)
|Utrecht
|-
|Certificate country name (default)
|NL
|-
|}

=== Editing the ''openssl.cnf'' configuration file===
When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big <enter> key.

First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits.

Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded.

So the changes we've made will amount to something like this:
[ CA_default ]
dir = /etc/ssl/ca
...
default_days = 370
...
[ req ]
default_bits = 2048
...
[ req_distinguished_name ]
0.organizationName_default = Saruman.biz
stateOrProvinceName_default = Utrecht
countryName_default = NL
Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want.

=== Editing the ''CA.sh'' script ===
Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts.

We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''.

With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this:

DAYS="-days 370" # 1 year
CADAYS="-days 5479" # 15 years
...
echo "Making CA certificate ..."
$REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \
-out ${CATOP}/$CAREQ

==the Certificate Authority root certificate==
Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair".

===Creating the CA root certificate key pair===
To generate the CA's public and private root certificate, as root, execute
/usr/lib/ssl/misc/CA.sh -newca
With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit <enter>.

Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).

For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves. 
Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/ssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key.

The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/ssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/ssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''.

So now we've got two root certificates, namely
* '''private''' key ''/etc/ssl/ca/private/cakey.pem'', and
* '''public''' key ''/etc/ssl/ca/cacert.pem''.
NEVER send your private key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here).

You can inspect your certificates (when you're in directory ''/etc/ssl/ca'') with commands like this:
openssl x509 -in cacert.pem -noout -text
openssl x509 -in cacert.pem -noout -dates
openssl x509 -in cacert.pem -noout -purpose
Note from the last command above, that this certificate is obviously a root certificate: it can verify the signature of everything but the kitchen sink.

In the same manner you can inspect your private key:
openssl rsa -in private/cakey.pem -noout -text

Note that this can be used to check if the private key and certificate belong together: the `modulus' and the `public exponent' portions in the private
key and the certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach:
openssl x509 -in cacert.pem -noout -modulus | openssl md5
openssl rsa -in private/cakey.pem -noout -modulus | openssl md5
And then compare these really shorter numbers. Both commands will output something like:
(stdin)= 96a281eca852b794a907186a9703ddf4
With overwhelming probability they will differ if the keys are different.

===We've got the CA certificate, now what?===
With the root CA certificates available to us, we've got the following things to do:
* guard very carefully the public and (especially) the private key file;
* sign certificates for our own use;
* distribute the public CA certificate to every machine/person that may need to verify certificates that we've signed.
The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. At the very least, you have to make sure the private key is owned by root or an administrative account, and is ''not'' world-readable. It might even be wise to remove the private key altogether, and keep it on a USB stick, and only read it when signing certificates.

The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section.

The last point means we need to send out our public CA certificate. In some cases, you can provide others with your ''.pem'' file, but in other cases you're better off providing a simpler ''.crt'' file. The difference is explained nicely at the [http://info.ssl.com/article.aspx?id=12149 ssl.com site]
To create a public CA certificate in .crt format you can issue the following command:
openssl x509 -outform der -in cacert.pem -out cacert.crt
By the way, it's usually better to distribute the public certificate with a more recognizable file name, such as ''saruman.biz.crt''

Certificate fundamentals

2016-10-29T20:12:05Z

Saruman!: corrected directory name - /etc/ssl not /etc/openssl

==Certificates, an introduction==
Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates.

Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera).

Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business.

==Creating the Certificate Authority (CA) - preparations==
To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters.

===Deciding on CA parameters===
'''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]).

How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days.

'''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key.

How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-)

'''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values:
* Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here.
* Country: NL (that's the Netherlands)
* Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it.
Maybe you want to provide more default information to your CA setup; just look further down on how to.

So the information we've decided upon is like this:
{| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5"
!style="background:#ffdead;"|Parameter
!style="background:#ffdead;"|value
|-
|root certificate encryption
|4096 bits
|-
|root certificate validity
|5479 days (15 years)
|-
|certificate store
|''/etc/ssl/ca''
|-
|default certificate validity
|370 days (1 year)
|-
|Organization name
|Saruman.biz
|-
|Certificate province/county name (default)
|Utrecht
|-
|Certificate country name (default)
|NL
|-
|}

=== Editing the ''openssl.cnf'' configuration file===
When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big <enter> key.

First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits.

Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded.

So the changes we've made will amount to something like this:
[ CA_default ]
dir = /etc/ssl/ca
...
default_days = 370
...
[ req ]
default_bits = 2048
...
[ req_distinguished_name ]
0.organizationName_default = Saruman.biz
stateOrProvinceName_default = Utrecht
countryName_default = NL
Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want.

=== Editing the ''CA.sh'' script ===
Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts.

We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''.

With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this:

DAYS="-days 370" # 1 year
CADAYS="-days 5479" # 15 years
...
echo "Making CA certificate ..."
$REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \
-out ${CATOP}/$CAREQ

==the Certificate Authority root certificate==
Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair".

===Creating the CA root certificate key pair===
To generate the CA's public and private root certificate, as root, execute
/usr/lib/ssl/misc/CA.sh -newca
With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit <enter>.

Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).

For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves. 
Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/ssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key.

The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/ssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/ssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''.

So now we've got two root certificates, namely
* '''private''' key ''/etc/ssl/ca/private/cakey.pem'', and
* '''public''' key ''/etc/ssl/ca/cacert.pem''.
NEVER send your private key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here).

You can inspect your certificates (when you're in directory ''/etc/ssl/ca'') with commands like this:
openssl x509 -in cacert.pem -noout -text
openssl x509 -in cacert.pem -noout -dates
openssl x509 -in cacert.pem -noout -purpose
Note from the last command above, that this certificate is obviously a root certificate: it can verify the signature of everything but the kitchen sink.

In the same manner you can inspect your private key:
openssl rsa -in private/cakey.pem -noout -text

Note that this can be used to check if the private key and certificate belong together: the `modulus' and the `public exponent' portions in the private
key and the certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach:
openssl x509 -in cacert.pem -noout -modulus | openssl md5
openssl rsa -in private/cakey.pem -noout -modulus | openssl md5
And then compare these really shorter numbers. Both commands will output something like:
(stdin)= 96a281eca852b794a907186a9703ddf4
With overwhelming probability they will differ if the keys are different.

===We've got the CA certificate, now what?===
With the root CA certificates available to us, we've got the following things to do:
* guard very carefully the public and (especially) the private key file;
* sign certificates for our own use;
* distribute the public CA certificate to every machine/person that may need to verify certificates that we've signed.
The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates.
The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section.
The last point means we need to send out our public CA certificate. In some cases, you can provide others with your ''.pem'' file, but in other cases you're better off providing a simpler ''.crt'' file. The difference is explained nicely at the [http://info.ssl.com/article.aspx?id=12149 ssl.com site]
To create a public CA certificate in .crt format you can issue the following command:
openssl x509 -outform der -in cacert.pem -out cacert.crt
By the way, it's usually better to distribute the public certificate with a more recognizable file name, such as ''saruman.biz.crt''

Certificate fundamentals

2016-10-29T20:06:52Z

Saruman!: /* We've got the CA certificate, now what? */ added crt conversion

==Certificates, an introduction==
Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates.

Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera).

Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business.

==Creating the Certificate Authority (CA) - preparations==
To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters.

===Deciding on CA parameters===
'''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]).

How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days.

'''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key.

How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-)

'''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values:
* Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here.
* Country: NL (that's the Netherlands)
* Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it.
Maybe you want to provide more default information to your CA setup; just look further down on how to.

So the information we've decided upon is like this:
{| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5"
!style="background:#ffdead;"|Parameter
!style="background:#ffdead;"|value
|-
|root certificate encryption
|4096 bits
|-
|root certificate validity
|5479 days (15 years)
|-
|certificate store
|''/etc/ssl/ca''
|-
|default certificate validity
|370 days (1 year)
|-
|Organization name
|Saruman.biz
|-
|Certificate province/county name (default)
|Utrecht
|-
|Certificate country name (default)
|NL
|-
|}

=== Editing the ''openssl.cnf'' configuration file===
When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big <enter> key.

First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits.

Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded.

So the changes we've made will amount to something like this:
[ CA_default ]
dir = /etc/ssl/ca
...
default_days = 370
...
[ req ]
default_bits = 2048
...
[ req_distinguished_name ]
0.organizationName_default = Saruman.biz
stateOrProvinceName_default = Utrecht
countryName_default = NL
Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want.

=== Editing the ''CA.sh'' script ===
Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts.

We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''.

With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this:

DAYS="-days 370" # 1 year
CADAYS="-days 5479" # 15 years
...
echo "Making CA certificate ..."
$REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \
-out ${CATOP}/$CAREQ

==the Certificate Authority root certificate==
Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair".

===Creating the CA root certificate key pair===
To generate the CA's public and private root certificate, as root, execute
/usr/lib/ssl/misc/CA.sh -newca
With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit <enter>.

Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).

For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves. 
Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key.

The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''.

So now we've got two root certificates, namely
* '''private''' key ''/etc/openssl/ca/private/cakey.pem'', and
* '''public''' key ''/etc/openssl/ca/cacert.pem''.
NEVER send your private key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here).

You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this:
openssl x509 -in cacert.pem -noout -text
openssl x509 -in cacert.pem -noout -dates
openssl x509 -in cacert.pem -noout -purpose
Note from the last command above, that this certificate is obviously a root certificate: it can verify the signature of everything but the kitchen sink.

In the same manner you can inspect your private key:
openssl rsa -in private/cakey.pem -noout -text

Note that this can be used to check if the private key and certificate belong together: the `modulus' and the `public exponent' portions in the private
key and the certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach:
openssl x509 -in cacert.pem -noout -modulus | openssl md5
openssl rsa -in private/cakey.pem -noout -modulus | openssl md5
And then compare these really shorter numbers. Both commands will output something like:
(stdin)= 96a281eca852b794a907186a9703ddf4
With overwhelming probability they will differ if the keys are different.

===We've got the CA certificate, now what?===
With the root CA certificates available to us, we've got the following things to do:
* guard very carefully the public and (especially) the private key file;
* sign certificates for our own use;
* distribute the public CA certificate to every machine/person that may need to verify certificates that we've signed.
The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates.
The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section.
The last point means we need to send out our public CA certificate. In some cases, you can provide others with your ''.pem'' file, but in other cases you're better off providing a simpler ''.crt'' file. The difference is explained nicely at the [http://info.ssl.com/article.aspx?id=12149 ssl.com site]
To create a public CA certificate in .crt format you can issue the following command:
openssl x509 -outform der -in cacert.pem -out cacert.crt
By the way, it's usually better to distribute the public certificate with a more recognizable file name, such as ''saruman.biz.crt''

Certificate fundamentals

2016-10-29T19:40:20Z

Saruman!: /* Creating the CA root certificate key pair */ expanded with checks

==Certificates, an introduction==
Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates.

Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera).

Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business.

==Creating the Certificate Authority (CA) - preparations==
To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters.

===Deciding on CA parameters===
'''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]).

How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days.

'''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key.

How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-)

'''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values:
* Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here.
* Country: NL (that's the Netherlands)
* Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it.
Maybe you want to provide more default information to your CA setup; just look further down on how to.

So the information we've decided upon is like this:
{| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5"
!style="background:#ffdead;"|Parameter
!style="background:#ffdead;"|value
|-
|root certificate encryption
|4096 bits
|-
|root certificate validity
|5479 days (15 years)
|-
|certificate store
|''/etc/ssl/ca''
|-
|default certificate validity
|370 days (1 year)
|-
|Organization name
|Saruman.biz
|-
|Certificate province/county name (default)
|Utrecht
|-
|Certificate country name (default)
|NL
|-
|}

=== Editing the ''openssl.cnf'' configuration file===
When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big <enter> key.

First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits.

Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded.

So the changes we've made will amount to something like this:
[ CA_default ]
dir = /etc/ssl/ca
...
default_days = 370
...
[ req ]
default_bits = 2048
...
[ req_distinguished_name ]
0.organizationName_default = Saruman.biz
stateOrProvinceName_default = Utrecht
countryName_default = NL
Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want.

=== Editing the ''CA.sh'' script ===
Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts.

We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''.

With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this:

DAYS="-days 370" # 1 year
CADAYS="-days 5479" # 15 years
...
echo "Making CA certificate ..."
$REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \
-out ${CATOP}/$CAREQ

==the Certificate Authority root certificate==
Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair".

===Creating the CA root certificate key pair===
To generate the CA's public and private root certificate, as root, execute
/usr/lib/ssl/misc/CA.sh -newca
With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit <enter>.

Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).

For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves. 
Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key.

The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''.

So now we've got two root certificates, namely
* '''private''' key ''/etc/openssl/ca/private/cakey.pem'', and
* '''public''' key ''/etc/openssl/ca/cacert.pem''.
NEVER send your private key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here).

You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this:
openssl x509 -in cacert.pem -noout -text
openssl x509 -in cacert.pem -noout -dates
openssl x509 -in cacert.pem -noout -purpose
Note from the last command above, that this certificate is obviously a root certificate: it can verify the signature of everything but the kitchen sink.

In the same manner you can inspect your private key:
openssl rsa -in private/cakey.pem -noout -text

Note that this can be used to check if the private key and certificate belong together: the `modulus' and the `public exponent' portions in the private
key and the certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach:
openssl x509 -in cacert.pem -noout -modulus | openssl md5
openssl rsa -in private/cakey.pem -noout -modulus | openssl md5
And then compare these really shorter numbers. Both commands will output something like:
(stdin)= 96a281eca852b794a907186a9703ddf4
With overwhelming probability they will differ if the keys are different.

===We've got the CA certificate, now what?===
With the root CA certificates available to us, we've got two things to do:
* guard very carefully the public and (especially) the private key file
* sign certificates for our own use
The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates.
The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section.

Certificate fundamentals

2016-02-23T09:23:28Z

Saruman!: reordered

==Certificates, an introduction==
Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates.

Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera).

Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business.

==Creating the Certificate Authority (CA) - preparations==
To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters.

===Deciding on CA parameters===
'''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]).

How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days.

'''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key.

How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-)

'''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values:
* Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here.
* Country: NL (that's the Netherlands)
* Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it.
Maybe you want to provide more default information to your CA setup; just look further down on how to.

So the information we've decided upon is like this:
{| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5"
!style="background:#ffdead;"|Parameter
!style="background:#ffdead;"|value
|-
|root certificate encryption
|4096 bits
|-
|root certificate validity
|5479 days (15 years)
|-
|certificate store
|''/etc/ssl/ca''
|-
|default certificate validity
|370 days (1 year)
|-
|Organization name
|Saruman.biz
|-
|Certificate province/county name (default)
|Utrecht
|-
|Certificate country name (default)
|NL
|-
|}

=== Editing the ''openssl.cnf'' configuration file===
When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big <enter> key.

First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits.

Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded.

So the changes we've made will amount to something like this:
[ CA_default ]
dir = /etc/ssl/ca
...
default_days = 370
...
[ req ]
default_bits = 2048
...
[ req_distinguished_name ]
0.organizationName_default = Saruman.biz
stateOrProvinceName_default = Utrecht
countryName_default = NL
Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want.

=== Editing the ''CA.sh'' script ===
Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts.

We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''.

With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this:

DAYS="-days 370" # 1 year
CADAYS="-days 5479" # 15 years
...
echo "Making CA certificate ..."
$REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \
-out ${CATOP}/$CAREQ

==the Certificate Authority root certificate==
Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair".

===Creating the CA root certificate key pair===
To generate the CA's public and private root certificate, as root, execute
/usr/lib/ssl/misc/CA.sh -newca
With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit <enter>.

Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).

For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves. 
Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key.

The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''.

So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here).

You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this:
openssl x509 -in cacert.pem -noout -text
openssl x509 -in cacert.pem -noout -dates
openssl x509 -in cacert.pem -noout -purpose
Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink.

===We've got the CA certificate, now what?===
With the root CA certificates available to us, we've got two things to do:
* guard very carefully the public and (especially) the private key file
* sign certificates for our own use
The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates.
The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section.

Certificate fundamentals

2016-02-23T09:19:31Z

Saruman!: /* Editing the CA.sh script */

==Certificates, an introduction==
Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates.

Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera).

Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business.

==Creating the Certificate Authority (CA) - preparations==
To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters.

===Deciding on CA parameters===
'''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]).

How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days.

'''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key.

How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-)

'''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values:
* Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here.
* Country: NL (that's the Netherlands)
* Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it.
Maybe you want to provide more default information to your CA setup; just look further down on how to.

So the information we've decided upon is like this:
{| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5"
!style="background:#ffdead;"|Parameter
!style="background:#ffdead;"|value
|-
|root certificate encryption
|4096 bits
|-
|root certificate validity
|5479 days (15 years)
|-
|certificate store
|''/etc/ssl/ca''
|-
|default certificate validity
|370 days (1 year)
|-
|Organization name
|Saruman.biz
|-
|Certificate province/county name (default)
|Utrecht
|-
|Certificate country name (default)
|NL
|-
|}

=== Editing the ''CA.sh'' script ===
Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script.

Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''.

With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this:

DAYS="-days 370" # 1 year
CADAYS="-days 5479" # 15 years
...
echo "Making CA certificate ..."
$REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \
-out ${CATOP}/$CAREQ

=== Editing the ''openssl.cnf'' configuration file===
When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big <enter> key.

First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits.

Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded.

So the changes we've made will amount to something like this:
[ CA_default ]
dir = /etc/ssl/ca
...
default_days = 370
...
[ req ]
default_bits = 2048
...
[ req_distinguished_name ]
0.organizationName_default = Saruman.biz
stateOrProvinceName_default = Utrecht
countryName_default = NL
Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want.

==the Certificate Authority root certificate==
Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair".

===Creating the CA root certificate key pair===
To generate the CA's public and private root certificate, as root, execute
/usr/lib/ssl/misc/CA.sh -newca
With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit <enter>.

Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).

For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves. 
Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key.

The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''.

So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here).

You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this:
openssl x509 -in cacert.pem -noout -text
openssl x509 -in cacert.pem -noout -dates
openssl x509 -in cacert.pem -noout -purpose
Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink.

===We've got the CA certificate, now what?===
With the root CA certificates available to us, we've got two things to do:
* guard very carefully the public and (especially) the private key file
* sign certificates for our own use
The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates.
The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section.

Certificate fundamentals

2016-02-23T09:02:29Z

Saruman!: /* Deciding on CA parameters */

==Certificates, an introduction==
Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates.

Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera).

Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business.

==Creating the Certificate Authority (CA) - preparations==
To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters.

===Deciding on CA parameters===
'''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]).

How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days.

'''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key.

How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-)

'''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values:
* Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here.
* Country: NL (that's the Netherlands)
* Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it.
Maybe you want to provide more default information to your CA setup; just look further down on how to.

So the information we've decided upon is like this:
{| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5"
!style="background:#ffdead;"|Parameter
!style="background:#ffdead;"|value
|-
|root certificate encryption
|4096 bits
|-
|root certificate validity
|5479 days (15 years)
|-
|certificate store
|''/etc/ssl/ca''
|-
|default certificate validity
|370 days (1 year)
|-
|Organization name
|Saruman.biz
|-
|Certificate province/county name (default)
|Utrecht
|-
|Certificate country name (default)
|NL
|-
|}

=== Editing the ''CA.sh'' script ===
Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script.

Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:2048''.

With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this:
<source lang="bash">
DAYS="-days 370" # 1 year
CADAYS="-days 5479" # 15 years
...
CATOP=/etc/ssl/ca
...
echo "Making CA certificate ..."
$REQ -new -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \
-out ${CATOP}/$CAREQ
</source>

=== Editing the ''openssl.cnf'' configuration file===
When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big <enter> key.

First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits.

Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded.

So the changes we've made will amount to something like this:
[ CA_default ]
dir = /etc/ssl/ca
...
default_days = 370
...
[ req ]
default_bits = 2048
...
[ req_distinguished_name ]
0.organizationName_default = Saruman.biz
stateOrProvinceName_default = Utrecht
countryName_default = NL
Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want.

==the Certificate Authority root certificate==
Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair".

===Creating the CA root certificate key pair===
To generate the CA's public and private root certificate, as root, execute
/usr/lib/ssl/misc/CA.sh -newca
With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit <enter>.

Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).

For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves. 
Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key.

The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''.

So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here).

You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this:
openssl x509 -in cacert.pem -noout -text
openssl x509 -in cacert.pem -noout -dates
openssl x509 -in cacert.pem -noout -purpose
Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink.

===We've got the CA certificate, now what?===
With the root CA certificates available to us, we've got two things to do:
* guard very carefully the public and (especially) the private key file
* sign certificates for our own use
The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates.
The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section.

Certificate fundamentals

2016-02-22T12:11:30Z

Saruman!: /* Creating the Certificate Authority (CA) - preparations */

==Certificates, an introduction==
Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates.

Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera).

Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business.

==Creating the Certificate Authority (CA) - preparations==
To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters.

===Deciding on CA parameters===
'''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]).

How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates from ten years earlies to wander around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days.

'''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our central server.

How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-)

'''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values:
* Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here.
* Province: Utrecht. Yep, that's a province in the Netherlands, and we live pretty close to it.
* Country: NL (that's the Netherlands)
Maybe you want to provide more default information to your CA setup; just look further down on how to.

So the information we've decided upon is like this:
{| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5"
!style="background:#ffdead;"|Parameter
!style="background:#ffdead;"|value
|-
|root certificate encryption
|4096 bits
|-
|root certificate validity
|5479 days (15 years)
|-
|certificate store
|''/etc/ssl/ca''
|-
|default certificate validity
|370 days (1 year)
|-
|Organization name
|Saruman.biz
|-
|Certificate province/county name (default)
|Utrecht
|-
|Certificate country name (default)
|NL
|-
|}

=== Editing the ''CA.sh'' script ===
Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script.

Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:2048''.

With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this:
<source lang="bash">
DAYS="-days 370" # 1 year
CADAYS="-days 5479" # 15 years
...
CATOP=/etc/ssl/ca
...
echo "Making CA certificate ..."
$REQ -new -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \
-out ${CATOP}/$CAREQ
</source>

=== Editing the ''openssl.cnf'' configuration file===
When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big <enter> key.

First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits.

Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded.

So the changes we've made will amount to something like this:
[ CA_default ]
dir = /etc/ssl/ca
...
default_days = 370
...
[ req ]
default_bits = 2048
...
[ req_distinguished_name ]
0.organizationName_default = Saruman.biz
stateOrProvinceName_default = Utrecht
countryName_default = NL
Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want.

==the Certificate Authority root certificate==
Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair".

===Creating the CA root certificate key pair===
To generate the CA's public and private root certificate, as root, execute
/usr/lib/ssl/misc/CA.sh -newca
With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit <enter>.

Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).

For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves. 
Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key.

The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''.

So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here).

You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this:
openssl x509 -in cacert.pem -noout -text
openssl x509 -in cacert.pem -noout -dates
openssl x509 -in cacert.pem -noout -purpose
Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink.

===We've got the CA certificate, now what?===
With the root CA certificates available to us, we've got two things to do:
* guard very carefully the public and (especially) the private key file
* sign certificates for our own use
The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates.
The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section.

Certificate fundamentals

2016-02-22T12:06:31Z

Saruman!: /* Deciding on CA parameters */

==Certificates, an introduction==
Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates.

Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera).

Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business.

==Creating the Certificate Authority (CA) - preparations==
To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed. Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters.

===Deciding on CA parameters===
'''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]).

How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates from ten years earlies to wander around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days.

'''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our central server.

How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accomodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-)

'''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values:
* Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here.
* Province: Utrecht. Yep, that's a province in the Netherlands, and we live pretty close to it.
* Country: NL (that's the Netherlands)
Maybe you want to provide more default information to your CA setup; just look further down on how to.

So the information we've decided upon is like this:
{| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5"
!style="background:#ffdead;"|Parameter
!style="background:#ffdead;"|value
|-
|root certificate encryption
|4096 bits
|-
|root certificate validity
|5479 days (15 years)
|-
|certificate store
|''/etc/ssl/ca''
|-
|default certificate validity
|370 days (1 year)
|-
|Organization name
|Saruman.biz
|-
|Certificate province/county name (default)
|Utrecht
|-
|Certificate country name (default)
|NL
|-
|}

=== Editing the ''CA.sh'' script ===
Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script.

Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:2048''.

With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this:
<source lang="bash">
DAYS="-days 370" # 1 year
CADAYS="-days 5479" # 15 years
...
CATOP=/etc/ssl/ca
...
echo "Making CA certificate ..."
$REQ -new -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \
-out ${CATOP}/$CAREQ
</source>

=== Editing the ''openssl.cnf'' configuration file===
When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big <enter> key.

First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits.

Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded.

So the changes we've made will amount to something like this:
[ CA_default ]
dir = /etc/ssl/ca
...
default_days = 370
...
[ req ]
default_bits = 2048
...
[ req_distinguished_name ]
0.organizationName_default = Saruman.biz
stateOrProvinceName_default = Utrecht
countryName_default = NL
Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want.

==the Certificate Authority root certificate==
Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair".

===Creating the CA root certificate key pair===
To generate the CA's public and private root certificate, as root, execute
/usr/lib/ssl/misc/CA.sh -newca
With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit <enter>.

Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).

For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves. 
Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key.

The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''.

So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here).

You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this:
openssl x509 -in cacert.pem -noout -text
openssl x509 -in cacert.pem -noout -dates
openssl x509 -in cacert.pem -noout -purpose
Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink.

===We've got the CA certificate, now what?===
With the root CA certificates available to us, we've got two things to do:
* guard very carefully the public and (especially) the private key file
* sign certificates for our own use
The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates.
The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section.

E-mail server section

2016-02-22T10:35:02Z

Saruman!: /* Inserting data */

==E-mail server setup==
What we want to accomplish here is the setup of a mail server with the following properties:
* can serve multiple mail domains
* can relay mail for other domains to other mail servers
* can have one or more mailboxes per domain
* users of these mailboxes can be virtual (do not need to have a Linux user account)
* can have multiple aliases per mailbox
* can forward mail for certain aliases to multiple mailboxes
For this type of mail server setup, we owe a great thankyou to [https://workaround.org/ispmail/squeeze Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003.

==Preparation==
We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems.

The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server.

The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail.

==Software installation==
As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is:
* ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol
At the same time we can - and must - purge the following packages:
* exim4
* exim4-base
* exim4-daemon-light
* exim4-config
In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix.

When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this:
* General type of mail configuration: Internet site
* System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting <enter>!
* Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster".
* Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this:
saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost
* Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself
* Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range)
* Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit.
* Character for local address extension: we leave it at ''+''
* Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only.
With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings.

Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well):
* ''postfix-doc'', the accompanying documentation;
* ''postfix-mysql'', necessary to have Postfix talk to our MySQL server;
* ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam;
* ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail;
* ''dovecot-pop3d'' is another daemon, but for the POP3 protocol.

==Virtual Mailman creation==
When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz).

To create this user, and his home directory, we can run the following commands:
groupadd -g 120 vmail
useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false
As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry.

To tell Postfix that this ''vmail'' user is someone special, we run
postconf -e virtual_uid_maps=static:120
postconf -e virtual_gid_maps=static:120
That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's.

==MySQL configuration==

===Database preparation===
We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this:
mysql -u root -p < create.vmail.sql
(This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view. 
A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly.

===Inserting data===
Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this:
mysql -u root -p vmail
mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz');
mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz');
mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz');
This has the effect of creating three entries. You can check that everything worked as planned by executing
mysql> select * from virtual_domains;
Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two.

Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section.

Whle still within the mysql client, we can now create users:
mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret'));
mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret'));
mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret'));
This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''.

The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works:
mysql> select * from virtual_users;
mysql> select * from view_users;

Should you need to update a user's password from the command line, you can use the following command, provided you've looked up that user's ''id'' :
UPDATE virtual_users set passwd = MD5('<password>') WHERE id = '<id>';

Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain".
mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination)
VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz');
mysql> INSERT INTO virtual_aliases (domain_id, source, destination)
VALUES (2, 'webmaster', 'j.doe@example.com');
mysql> INSERT INTO virtual_aliases (domain_id, destination)
VALUES (1, 'mike@saruman.biz');
mysql> INSERT INTO virtual_aliases (domain_id, destination)
VALUES (2, 'mike@saruman.biz');
mysql> INSERT INTO virtual_aliases (domain_id, destination)
VALUES (3, 'webmaster@saruman.biz');

Again, we don't need to add the ''id'' value any more after the first ever insertion into this table.

We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view:
mysql> select * from virtual_aliases;
mysql> select * from view_aliases;

== Postfix configuration for MySQL lookups==
Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases.

===Virtual mail domains lookup===

Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content:
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT 1 FROM virtual_domains WHERE vdomain='%s'
Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains":
postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf
Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret".

=== Virtual mail user lookup===
Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content:
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT 1 FROM view_users WHERE email='%s'
Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping:
postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf
The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e.
postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf
should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration.

=== Virtual alias lookup===
Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'':
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT destination FROM view_aliases WHERE email='%s'
And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'':
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT email FROM view_users WHERE email='%s'

Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping:
postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf
The lookup of virtual aliases should now work as designed:
postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf
postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf
If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper.

===Finishing up configuration files===
When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus:
chown root:postfix /etc/postfix/mysql-*.cf
chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf
This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all.

==Configuring mail delivery through Dovecot LDA==
E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA.
===Enabling the Dovecot daemon===
To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'':
dovecot unix - n n - - pipe
flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient}
This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable:
postfix reload
postconf -e virtual_transport=dovecot
postconf -e dovecot_destination_recipient_limit=1
===Dovecot default configuration===
Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads
protocols = imap imaps pop3 pop3s
(which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#mail_location ='', and change it to
mail_location = maildir:/data/vmail/%d/%n/Maildir
This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format.
Next look for a section called "auth default". First define the allowed authentication mechanisms:
mechanisms = plain login
Then inside that same section you need to uncomment:
passdb sql {
args = /etc/dovecot/dovecot-sql.conf
}
which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and:
userdb static {
args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes
}
to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well.

Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is
namespace private {
separator = .
prefix =
inbox = yes
}
However, your mileage may vary.

You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users.

Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section):
socket listen {
master {
path = /var/run/dovecot/auth-master
mode = 0600
user = vmail
}
client {
path = /var/spool/postfix/private/auth
mode = 0660
user = postfix
group = postfix
}
}

Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts:
protocol lda {
log_path = /var/log/appslog/mail/dovecot-deliver.log
auth_socket_path = /var/run/dovecot/auth-master
postmaster_address = postmaster@saruman.biz
mail_plugins = cmusieve
global_script_path = /data/vmail/globalsieverc
}

You could change the log path to "log_path =" With a empty logpath syslog will log the events.

Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are
driver = mysql
connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret
default_pass_scheme = PLAIN-MD5
password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u';
When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file.
chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf
chgrp vmail /etc/dovecot/dovecot.conf
chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf
/etc/init.d/dovecot restart

To get some more logging in the case something goes wrong. Uncomment the folling and change to yes.
auth_verbose = yes
auth_debug = yes
auth_debug_passwords = yes

===Dovecot SSL configuration===
Out of the (Debian) box, Dovecot is SSL-enabled. We'll now replace the generic SSL-certificate, generated for the host by the Dovecot installation script, by our own certificate. To ths end, we first [[Creating_digital_certificates_with_our_root_certificate | generate an appropriate certificate]], e.g. an SSL wildcard certificate: "*.saruman.biz". This results in a public and a private certificate, both of which must be placed somewhere where Dovecot expects them and can read them.

By default, Dovecot expects the following locations/filenames/owner/attributes:
/etc/ssl/certs/dovecot.pem -rw-r--r-- root:dovecot 4624 bytes
/etc/ssl/private/dovecot.pem -rw------- root:dovecot 1743 bytes
If we may make a suggestion: rename the generated certificates in both locations to dovecot.pem.bak, place your generated certificates in their place, and set the owner/permissions like displayed here.

However, if you've generated your own keys, you might have used a passphrase on the private key. You'll have to tell dovecot about it in its configuration file /etc/dovecot/dovecot.conf. To this end, edit the corresponding section by uncommenting the "ssl_" lines, and using your private key password (e.g. "zM7Ertq12") in the appropriate line:
ssl_cert_file = /etc/ssl/certs/dovecot.pem
ssl_key_file = /etc/ssl/private/dovecot.pem

# If key file is password protected, give the password here. Alternatively
# give it when starting dovecot with -p parameter.
ssl_key_password = zM7Ertq12
Naturally you are free to place the keys in a different location, and/or use a different name...

==Finishing up==

This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration.

===''smtpd'' TLS encryption===
The first addition we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection:
postconf -e mynetworks=
Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using
postconf -e smtpd_use_tls=yes
postconf -e smtpd_tls_auth_only=yes
Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself.

If TLS works, you'll probably want to change the certificate as you have for Dovecot in the previous section. This is again pretty easy. If you haven't yet, now is the time to [[Creating_digital_certificates_with_our_root_certificate | creating that custom SSL certificate]] for our mail server - but you have to make sure that you DON'T use a password on the private key. Unlike Dovecot, Postfix cannot be told the password to the private key somewhere.

For starters, look at the TLS-section of your ''main.cf'' that you currently have. Chances are a big chunk of it looks like this:
# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_use_tls=yes
Now all you need to do is replace the name of the snakeoil-keys with those of appropriate ssl-certificates, the private key of which needs to be NOT passphrase-protected. For this you could copy the Dovecot certificates, if you strip that passphrase in the manner described in the [[Creating_digital_certificates_with_our_root_certificate#Creating_an_SSL_certificate | SSL certificate section]]. The ''main.cf'' then would become:
# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/postfix.pem
smtpd_tls_key_file=/etc/ssl/private/postfix.key
smtpd_use_tls=yes
Restart Postfix, and presto.

=== Other additions ===
If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. One page that we want to direct you to now, is
* [[Antispam measures]] for our Postfix mailserver

E-mail server section

2016-02-22T10:32:40Z

Saruman!: /* Inserting data */

==E-mail server setup==
What we want to accomplish here is the setup of a mail server with the following properties:
* can serve multiple mail domains
* can relay mail for other domains to other mail servers
* can have one or more mailboxes per domain
* users of these mailboxes can be virtual (do not need to have a Linux user account)
* can have multiple aliases per mailbox
* can forward mail for certain aliases to multiple mailboxes
For this type of mail server setup, we owe a great thankyou to [https://workaround.org/ispmail/squeeze Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003.

==Preparation==
We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems.

The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server.

The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail.

==Software installation==
As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is:
* ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol
At the same time we can - and must - purge the following packages:
* exim4
* exim4-base
* exim4-daemon-light
* exim4-config
In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix.

When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this:
* General type of mail configuration: Internet site
* System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting <enter>!
* Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster".
* Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this:
saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost
* Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself
* Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range)
* Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit.
* Character for local address extension: we leave it at ''+''
* Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only.
With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings.

Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well):
* ''postfix-doc'', the accompanying documentation;
* ''postfix-mysql'', necessary to have Postfix talk to our MySQL server;
* ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam;
* ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail;
* ''dovecot-pop3d'' is another daemon, but for the POP3 protocol.

==Virtual Mailman creation==
When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz).

To create this user, and his home directory, we can run the following commands:
groupadd -g 120 vmail
useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false
As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry.

To tell Postfix that this ''vmail'' user is someone special, we run
postconf -e virtual_uid_maps=static:120
postconf -e virtual_gid_maps=static:120
That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's.

==MySQL configuration==

===Database preparation===
We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this:
mysql -u root -p < create.vmail.sql
(This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view. 
A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly.

===Inserting data===
Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this:
mysql -u root -p vmail
mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz');
mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz');
mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz');
This has the effect of creating three entries. You can check that everything worked as planned by executing
mysql> select * from virtual_domains;
Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two.

Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section.

Whle still within the mysql client, we can now create users:
mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret'));
mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret'));
mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret'));
This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''.

The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works:
mysql> select * from virtual_users;
mysql> select * from view_users;

Should you need to update a user's password from the command line, you can use the following command, provided you've looked up that user's ''id'' :
UPDATE virtual_users set passwd = 'MD5('<password>')' WHERE id = '<id>';

Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain".
mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination)
VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz');
mysql> INSERT INTO virtual_aliases (domain_id, source, destination)
VALUES (2, 'webmaster', 'j.doe@example.com');
mysql> INSERT INTO virtual_aliases (domain_id, destination)
VALUES (1, 'mike@saruman.biz');
mysql> INSERT INTO virtual_aliases (domain_id, destination)
VALUES (2, 'mike@saruman.biz');
mysql> INSERT INTO virtual_aliases (domain_id, destination)
VALUES (3, 'webmaster@saruman.biz');

Again, we don't need to add the ''id'' value any more after the first ever insertion into this table.

We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view:
mysql> select * from virtual_aliases;
mysql> select * from view_aliases;

== Postfix configuration for MySQL lookups==
Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases.

===Virtual mail domains lookup===

Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content:
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT 1 FROM virtual_domains WHERE vdomain='%s'
Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains":
postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf
Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret".

=== Virtual mail user lookup===
Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content:
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT 1 FROM view_users WHERE email='%s'
Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping:
postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf
The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e.
postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf
should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration.

=== Virtual alias lookup===
Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'':
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT destination FROM view_aliases WHERE email='%s'
And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'':
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT email FROM view_users WHERE email='%s'

Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping:
postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf
The lookup of virtual aliases should now work as designed:
postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf
postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf
If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper.

===Finishing up configuration files===
When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus:
chown root:postfix /etc/postfix/mysql-*.cf
chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf
This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all.

==Configuring mail delivery through Dovecot LDA==
E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA.
===Enabling the Dovecot daemon===
To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'':
dovecot unix - n n - - pipe
flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient}
This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable:
postfix reload
postconf -e virtual_transport=dovecot
postconf -e dovecot_destination_recipient_limit=1
===Dovecot default configuration===
Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads
protocols = imap imaps pop3 pop3s
(which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#mail_location ='', and change it to
mail_location = maildir:/data/vmail/%d/%n/Maildir
This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format.
Next look for a section called "auth default". First define the allowed authentication mechanisms:
mechanisms = plain login
Then inside that same section you need to uncomment:
passdb sql {
args = /etc/dovecot/dovecot-sql.conf
}
which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and:
userdb static {
args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes
}
to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well.

Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is
namespace private {
separator = .
prefix =
inbox = yes
}
However, your mileage may vary.

You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users.

Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section):
socket listen {
master {
path = /var/run/dovecot/auth-master
mode = 0600
user = vmail
}
client {
path = /var/spool/postfix/private/auth
mode = 0660
user = postfix
group = postfix
}
}

Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts:
protocol lda {
log_path = /var/log/appslog/mail/dovecot-deliver.log
auth_socket_path = /var/run/dovecot/auth-master
postmaster_address = postmaster@saruman.biz
mail_plugins = cmusieve
global_script_path = /data/vmail/globalsieverc
}

You could change the log path to "log_path =" With a empty logpath syslog will log the events.

Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are
driver = mysql
connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret
default_pass_scheme = PLAIN-MD5
password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u';
When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file.
chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf
chgrp vmail /etc/dovecot/dovecot.conf
chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf
/etc/init.d/dovecot restart

To get some more logging in the case something goes wrong. Uncomment the folling and change to yes.
auth_verbose = yes
auth_debug = yes
auth_debug_passwords = yes

===Dovecot SSL configuration===
Out of the (Debian) box, Dovecot is SSL-enabled. We'll now replace the generic SSL-certificate, generated for the host by the Dovecot installation script, by our own certificate. To ths end, we first [[Creating_digital_certificates_with_our_root_certificate | generate an appropriate certificate]], e.g. an SSL wildcard certificate: "*.saruman.biz". This results in a public and a private certificate, both of which must be placed somewhere where Dovecot expects them and can read them.

By default, Dovecot expects the following locations/filenames/owner/attributes:
/etc/ssl/certs/dovecot.pem -rw-r--r-- root:dovecot 4624 bytes
/etc/ssl/private/dovecot.pem -rw------- root:dovecot 1743 bytes
If we may make a suggestion: rename the generated certificates in both locations to dovecot.pem.bak, place your generated certificates in their place, and set the owner/permissions like displayed here.

However, if you've generated your own keys, you might have used a passphrase on the private key. You'll have to tell dovecot about it in its configuration file /etc/dovecot/dovecot.conf. To this end, edit the corresponding section by uncommenting the "ssl_" lines, and using your private key password (e.g. "zM7Ertq12") in the appropriate line:
ssl_cert_file = /etc/ssl/certs/dovecot.pem
ssl_key_file = /etc/ssl/private/dovecot.pem

# If key file is password protected, give the password here. Alternatively
# give it when starting dovecot with -p parameter.
ssl_key_password = zM7Ertq12
Naturally you are free to place the keys in a different location, and/or use a different name...

==Finishing up==

This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration.

===''smtpd'' TLS encryption===
The first addition we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection:
postconf -e mynetworks=
Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using
postconf -e smtpd_use_tls=yes
postconf -e smtpd_tls_auth_only=yes
Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself.

If TLS works, you'll probably want to change the certificate as you have for Dovecot in the previous section. This is again pretty easy. If you haven't yet, now is the time to [[Creating_digital_certificates_with_our_root_certificate | creating that custom SSL certificate]] for our mail server - but you have to make sure that you DON'T use a password on the private key. Unlike Dovecot, Postfix cannot be told the password to the private key somewhere.

For starters, look at the TLS-section of your ''main.cf'' that you currently have. Chances are a big chunk of it looks like this:
# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_use_tls=yes
Now all you need to do is replace the name of the snakeoil-keys with those of appropriate ssl-certificates, the private key of which needs to be NOT passphrase-protected. For this you could copy the Dovecot certificates, if you strip that passphrase in the manner described in the [[Creating_digital_certificates_with_our_root_certificate#Creating_an_SSL_certificate | SSL certificate section]]. The ''main.cf'' then would become:
# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/postfix.pem
smtpd_tls_key_file=/etc/ssl/private/postfix.key
smtpd_use_tls=yes
Restart Postfix, and presto.

=== Other additions ===
If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. One page that we want to direct you to now, is
* [[Antispam measures]] for our Postfix mailserver

OpenLDAP

2016-02-21T21:44:27Z

Saruman!: /* Post-install reconfiguration */

Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]]

== OpenLDAP installation==
Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23.

===Standard installation===
Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities
sudo apt-get install ldap-utils
This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd"
sudo apt-get install slapd
This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc'').

The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>.
The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are:
* a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan"
* a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan"
Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on.
<references/>

===Testing the installation===
After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'':
root@easton2:~# '''nmap -p 389 localhost'''

Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST
Interesting ports on localhost (127.0.0.1):
PORT STATE SERVICE
389/tcp open ldap

Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds
root@easton2:~#'''_'''

Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server:
root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts'''
# extended LDIF
#
# LDAPv3
# base <> with scope baseObject
# filter: (objectclass=*)
# requesting: namingContexts
#

#
dn:
namingContexts: dc=amber,dc=lan

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1
root@easton2:~# '''_'''
With this command, we do a search using
* basic authentication (instead of one encrypted with SASL),
* searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree),
* looking for base object only (instead of a one-level search, a subtree search, or a children-search),
* filtering for objects of any class,
* asking for the naming context of the result.
The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass).

Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one:
root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"'''
Enter LDAP Password:
ldap_bind: Invalid credentials (49)
root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"'''
Enter LDAP Password:
# extended LDIF
#
# LDAPv3
# base <> (default) with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#

# search result
search: 2
result: 32 No such object

# numResponses: 1
root@easton2:~# '''_'''
Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera.

===Post-install reconfiguration===
Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on.

To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this:
omit OpenLDAP config: no
DNS domain name: saruman.biz
Organization name: Saruman
Administrator passwd: wEt3udes
Database backend: MDB
DB remove after purge: yes
Move old DB: yes
Allow LDAPv2: no
As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it:
* a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz"
* a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz"
Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backups/unknown-2.4.40+dfsg-1+deb8u2.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it.

The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database or something similar. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with one of the specialized databases provided with Debian/OpenLDAP. Now, for the database backend, we have the choice between the following flavours:
* the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access.
* the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply.
* the ''mdb'' backend is a transactional backend built on OpenLDAP's [https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database Lightning Memory-Mapped Database] (LMDB).
In Debian 8.0 "Jessie" with OpenLDAP 2.4.40, MDB is the default backend.

==OpenLDAP server configuration==
(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php) As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes.

The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files.

===Check the current LDAP configuration===
From the command line, there really are several ways to check the current LDAP configuration:
* from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names:
root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
dn: cn=config

dn: cn=module{0},cn=config

dn: cn=schema,cn=config

dn: cn={0}core,cn=schema,cn=config

dn: cn={1}cosine,cn=schema,cn=config

dn: cn={2}nis,cn=schema,cn=config

dn: cn={3}inetorgperson,cn=schema,cn=config

dn: olcBackend={0}hdb,cn=config

dn: olcDatabase={-1}frontend,cn=config

dn: olcDatabase={0}config,cn=config

dn: olcDatabase={1}hdb,cn=config

root@easton2:/etc/ldap# '''_'''

* to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command:
root@easton2:/etc/ldap# '''slapcat -b cn=config'''
dn: cn=config
objectClass: olcGlobal
cn: config
olcArgsFile: /var/run/slapd/slapd.args
olcLogLevel: none
olcPidFile: /var/run/slapd/slapd.pid
olcToolThreads: 1
'''''(more LDIF texts)'''''
entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9
creatorsName: cn=admin,cn=config
createTimestamp: 20110413174103Z
entryCSN: 20110413174103.641065Z#000000#000#000000
modifiersName: cn=admin,cn=config
modifyTimestamp: 20110413174103Z
root@easton2:/etc/ldap# '''_'''
: As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided.
* you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories.
Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI.

===Adding or modifying the cn=config admin password===
To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise:
root@easton2:/etc/ldap# '''slappasswd -h {MD5}'''
New password:
Re-enter new password:
{MD5}d5axCh6gYGjhfK4PGs09us==
root@easton2:/etc/ldap# '''_'''
Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command.
root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
dn: olcDatabase={0}config,cn=config
olcRootDN: cn=admin,cn=config

root@easton2:/etc/ldap# '''_'''
Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server. 
Now we can stick in a new password. If no password is present, you can use this interactive procedure:
root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
'''dn: olcDatabase={0}config,cn=config'''
'''add: olcRootPW'''
'''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us=='''

modifying entry "olcDatabase={0}config,cn=config"

root@easton2:/etc/ldap# '''_'''
Note the following points:
* we use the olcDatabase location as found with the previous ''ldapsearch'' command;
* we input the MD5 password that we've generated previously;
* as soon as you put in an empty line, the entry gets added;
* you have to use CTRL-D to end this interactive mode;
* if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''.

We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content:
dn: olcDatabase={0}config,cn=config
changetype: modify
add: olcRootPW
olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==
If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using
root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
modifying entry "olcDatabase={0}config,cn=config"

root@easton2:/tmp# '''_'''

==Adding or modifying (configuration) information==
The simple way of changing anything in the database goes like this:
===Method 1: interactive CLI tool===
As an example, let's add an index to the configuration. We'll start by seeing which indices already exist, then interactively add two indices. Finally, we check that the indices are there:
root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex'''
dn: olcDatabase={1}hdb,cn=config
olcDbIndex: objectClass eq

root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
'''dn: olcDatabase={1}hdb,cn=config'''
'''add: olcDbIndex'''
'''olcDbIndex: cn eq'''
'''olcDbIndex: uid eq'''

modifying entry "olcDatabase={1}hdb,cn=config"

root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex'''
dn: olcDatabase={1}hdb,cn=config
olcDbIndex: objectClass eq
olcDbIndex: cn eq
olcDbIndex: uid eq

root@easton2:/tmp# '''_'''
(And ofcourse we press ctrl-D to end interactive mode). Note: we can /modify multiple attributes in one stanza, but we can also add multiple objects/attributes in one ''ldapmodify'' session:
* If you input an empty line, you can start another ''dn:'' line, and perform another action;
* If you input a minus sign by itself on a line, then OpenLDAP will assume you'll be performing another action in/on the same object.

Modifying works almost the same; we only need keyword ''replace'' instead of ''add'':
root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel'''
dn: cn=config
olcLogLevel: none
root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
'''dn: cn=config'''
'''changetype: modify'''
'''replace: olcLogLevel'''
'''olcLogLevel: stats'''

modifying entry "cn=config"

root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel'''
dn: cn=config
olcLogLevel: stats

root@easton2:/tmp# '''_'''
Note the ''-s base'' option that limits the search for the ''olcLogLevel'' attribute to the ''cn=config'' container.

Deleting information from an LDAP tree rarely ever happens, because once an attribute is used for anything, you aren't allowed to delete it, only modify it. However, if you want to delete anything, you can use the changetype "modify" with action "delete":
root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
'''dn: olcDatabase={0}config,cn=config'''
'''changetype: modify'''
'''delete: olcRootPW'''

modifying entry "olcDatabase={0}config,cn=config"

root@easton2:/tmp# '''_'''

===Method 2: use an ldif file===
===Method 3: use an LDAP browser===
With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk.

==Adding schemas==
A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added.
===Checking existing schemas===
Let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box:
root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn'''
dn: cn=schema,cn=config

dn: cn={0}core,cn=schema,cn=config

dn: cn={1}cosine,cn=schema,cn=config

dn: cn={2}nis,cn=schema,cn=config

dn: cn={3}inetorgperson,cn=schema,cn=config

root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema'''
total 40
-rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif
-rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif
-rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif
-rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif
root@easton2:/tmp# '''_'''
===Creating a suitable LDIF file for the schema===
To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command.
Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first have to convert this to a suitable LDIF file. This can be done using ''slaptest'', however ''slaptest'' requires access to the other schemas that your new schema is building on. So we now do this:
* We create a file ''schema_convert.conf'' with the content shown below. Note that we're including the schema files of all the schemas that are already in our LDAP server. Furthermore, because we may need it again with the next schema addition, it makes sense to save this file under ''/etc/ldap/schema'':
include /etc/ldap/schema/core.schema
include /etc/ldap/schema/cosine.schema
include /etc/ldap/schema/nis.schema
include /etc/ldap/schema/inetorgperson.schema
include /etc/ldap/schema/samba.schema
* now we create a working directory where ''slaptest'' can put our new LDIF file, and have ''slaptest'' create the configuration:
root@easton2:/tmp# '''mkdir /tmp/ldif_output'''
root@easton2:/tmp# '''slaptest -f /etc/ldap/schema/schema_convert.conf -F /tmp/ldif_output'''
config file testing succeeded
root@easton2:/tmp# '''_'''
* The previous step has created a directory structure under ''/tmp/ldif_output'' that actually mirrors the config directory ''/etc/ldap/slapd.d/cn=config/cn=schema'', but it contains a shiny new ''cn={4}samba.ldif'' file. We need to edit this file a bit before we can actually feed it to the LDAP server. Thus we'll edit it using (note the extra backslashes to escape the equal-sign and curly brackets):
root@easton2:/tmp# '''vi /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif'''
* We need to change and edit some parts of ''cn={4}samba.ldif'':
** Near the top we find ''dn: cn={4}samba''. We'll change this to the correct distinguished name ''dn: cn=samba,cn=schema,cn=config''
** Also near the top: ''cn: {4}samba''. We'll change this to ''cn: samba''
** The last seven lines look like the bit below - we need to remove these lines:
structuralObjectClass: olcSchemaConfig
entryUUID: f19250ba-1057-1031-88b7-8301a25f1d46
creatorsName: cn=config
createTimestamp: 20120401150603Z
entryCSN: 20120401150603.478495Z#000000#000#000000
modifiersName: cn=config
modifyTimestamp: 20120401150603Z
* We'll store the cleaned up LDIF file in ''/etc/ldap/schema'' with the originating schema file
root@easton2:/tmp# '''mv /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif /etc/ldap/schema/samba.ldif'''
root@easton2:/tmp# '''_'''
===Inserting the LDIF file in the LDAP server===
Time to actually invoke ''ldapadd'' which can put this schema in our LDAP server.
root@easton2:/tmp# '''ldapadd -QY EXTERNAL -H ldapi:/// -f /etc/ldap/schema/samba.ldif'''
adding new entry "cn=samba,cn=schema,cn=config"
root@easton2:/tmp# '''_'''

OpenLDAP

2016-02-21T21:39:39Z

Saruman!: /* Post-install reconfiguration */

Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]]

== OpenLDAP installation==
Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23.

===Standard installation===
Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities
sudo apt-get install ldap-utils
This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd"
sudo apt-get install slapd
This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc'').

The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>.
The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are:
* a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan"
* a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan"
Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on.
<references/>

===Testing the installation===
After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'':
root@easton2:~# '''nmap -p 389 localhost'''

Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST
Interesting ports on localhost (127.0.0.1):
PORT STATE SERVICE
389/tcp open ldap

Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds
root@easton2:~#'''_'''

Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server:
root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts'''
# extended LDIF
#
# LDAPv3
# base <> with scope baseObject
# filter: (objectclass=*)
# requesting: namingContexts
#

#
dn:
namingContexts: dc=amber,dc=lan

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1
root@easton2:~# '''_'''
With this command, we do a search using
* basic authentication (instead of one encrypted with SASL),
* searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree),
* looking for base object only (instead of a one-level search, a subtree search, or a children-search),
* filtering for objects of any class,
* asking for the naming context of the result.
The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass).

Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one:
root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"'''
Enter LDAP Password:
ldap_bind: Invalid credentials (49)
root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"'''
Enter LDAP Password:
# extended LDIF
#
# LDAPv3
# base <> (default) with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#

# search result
search: 2
result: 32 No such object

# numResponses: 1
root@easton2:~# '''_'''
Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera.

===Post-install reconfiguration===
Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on.

To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this:
omit OpenLDAP config: no
DNS domain name: saruman.biz
Organization name: Saruman
Administrator passwd: wEt3udes
Database backend: MDB
DB remove after purge: yes
Move old DB: yes
Allow LDAPv2: no
As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it:
* a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz"
* a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz"
Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backups/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it.

The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours:
* the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access.
* the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply.
In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend.

==OpenLDAP server configuration==
(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php) As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes.

The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files.

===Check the current LDAP configuration===
From the command line, there really are several ways to check the current LDAP configuration:
* from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names:
root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
dn: cn=config

dn: cn=module{0},cn=config

dn: cn=schema,cn=config

dn: cn={0}core,cn=schema,cn=config

dn: cn={1}cosine,cn=schema,cn=config

dn: cn={2}nis,cn=schema,cn=config

dn: cn={3}inetorgperson,cn=schema,cn=config

dn: olcBackend={0}hdb,cn=config

dn: olcDatabase={-1}frontend,cn=config

dn: olcDatabase={0}config,cn=config

dn: olcDatabase={1}hdb,cn=config

root@easton2:/etc/ldap# '''_'''

* to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command:
root@easton2:/etc/ldap# '''slapcat -b cn=config'''
dn: cn=config
objectClass: olcGlobal
cn: config
olcArgsFile: /var/run/slapd/slapd.args
olcLogLevel: none
olcPidFile: /var/run/slapd/slapd.pid
olcToolThreads: 1
'''''(more LDIF texts)'''''
entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9
creatorsName: cn=admin,cn=config
createTimestamp: 20110413174103Z
entryCSN: 20110413174103.641065Z#000000#000#000000
modifiersName: cn=admin,cn=config
modifyTimestamp: 20110413174103Z
root@easton2:/etc/ldap# '''_'''
: As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided.
* you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories.
Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI.

===Adding or modifying the cn=config admin password===
To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise:
root@easton2:/etc/ldap# '''slappasswd -h {MD5}'''
New password:
Re-enter new password:
{MD5}d5axCh6gYGjhfK4PGs09us==
root@easton2:/etc/ldap# '''_'''
Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command.
root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
dn: olcDatabase={0}config,cn=config
olcRootDN: cn=admin,cn=config

root@easton2:/etc/ldap# '''_'''
Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server. 
Now we can stick in a new password. If no password is present, you can use this interactive procedure:
root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
'''dn: olcDatabase={0}config,cn=config'''
'''add: olcRootPW'''
'''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us=='''

modifying entry "olcDatabase={0}config,cn=config"

root@easton2:/etc/ldap# '''_'''
Note the following points:
* we use the olcDatabase location as found with the previous ''ldapsearch'' command;
* we input the MD5 password that we've generated previously;
* as soon as you put in an empty line, the entry gets added;
* you have to use CTRL-D to end this interactive mode;
* if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''.

We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content:
dn: olcDatabase={0}config,cn=config
changetype: modify
add: olcRootPW
olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==
If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using
root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
modifying entry "olcDatabase={0}config,cn=config"

root@easton2:/tmp# '''_'''

==Adding or modifying (configuration) information==
The simple way of changing anything in the database goes like this:
===Method 1: interactive CLI tool===
As an example, let's add an index to the configuration. We'll start by seeing which indices already exist, then interactively add two indices. Finally, we check that the indices are there:
root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex'''
dn: olcDatabase={1}hdb,cn=config
olcDbIndex: objectClass eq

root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
'''dn: olcDatabase={1}hdb,cn=config'''
'''add: olcDbIndex'''
'''olcDbIndex: cn eq'''
'''olcDbIndex: uid eq'''

modifying entry "olcDatabase={1}hdb,cn=config"

root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex'''
dn: olcDatabase={1}hdb,cn=config
olcDbIndex: objectClass eq
olcDbIndex: cn eq
olcDbIndex: uid eq

root@easton2:/tmp# '''_'''
(And ofcourse we press ctrl-D to end interactive mode). Note: we can /modify multiple attributes in one stanza, but we can also add multiple objects/attributes in one ''ldapmodify'' session:
* If you input an empty line, you can start another ''dn:'' line, and perform another action;
* If you input a minus sign by itself on a line, then OpenLDAP will assume you'll be performing another action in/on the same object.

Modifying works almost the same; we only need keyword ''replace'' instead of ''add'':
root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel'''
dn: cn=config
olcLogLevel: none
root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
'''dn: cn=config'''
'''changetype: modify'''
'''replace: olcLogLevel'''
'''olcLogLevel: stats'''

modifying entry "cn=config"

root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel'''
dn: cn=config
olcLogLevel: stats

root@easton2:/tmp# '''_'''
Note the ''-s base'' option that limits the search for the ''olcLogLevel'' attribute to the ''cn=config'' container.

Deleting information from an LDAP tree rarely ever happens, because once an attribute is used for anything, you aren't allowed to delete it, only modify it. However, if you want to delete anything, you can use the changetype "modify" with action "delete":
root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///'''
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
'''dn: olcDatabase={0}config,cn=config'''
'''changetype: modify'''
'''delete: olcRootPW'''

modifying entry "olcDatabase={0}config,cn=config"

root@easton2:/tmp# '''_'''

===Method 2: use an ldif file===
===Method 3: use an LDAP browser===
With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk.

==Adding schemas==
A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added.
===Checking existing schemas===
Let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box:
root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn'''
dn: cn=schema,cn=config

dn: cn={0}core,cn=schema,cn=config

dn: cn={1}cosine,cn=schema,cn=config

dn: cn={2}nis,cn=schema,cn=config

dn: cn={3}inetorgperson,cn=schema,cn=config

root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema'''
total 40
-rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif
-rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif
-rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif
-rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif
root@easton2:/tmp# '''_'''
===Creating a suitable LDIF file for the schema===
To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command.
Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first have to convert this to a suitable LDIF file. This can be done using ''slaptest'', however ''slaptest'' requires access to the other schemas that your new schema is building on. So we now do this:
* We create a file ''schema_convert.conf'' with the content shown below. Note that we're including the schema files of all the schemas that are already in our LDAP server. Furthermore, because we may need it again with the next schema addition, it makes sense to save this file under ''/etc/ldap/schema'':
include /etc/ldap/schema/core.schema
include /etc/ldap/schema/cosine.schema
include /etc/ldap/schema/nis.schema
include /etc/ldap/schema/inetorgperson.schema
include /etc/ldap/schema/samba.schema
* now we create a working directory where ''slaptest'' can put our new LDIF file, and have ''slaptest'' create the configuration:
root@easton2:/tmp# '''mkdir /tmp/ldif_output'''
root@easton2:/tmp# '''slaptest -f /etc/ldap/schema/schema_convert.conf -F /tmp/ldif_output'''
config file testing succeeded
root@easton2:/tmp# '''_'''
* The previous step has created a directory structure under ''/tmp/ldif_output'' that actually mirrors the config directory ''/etc/ldap/slapd.d/cn=config/cn=schema'', but it contains a shiny new ''cn={4}samba.ldif'' file. We need to edit this file a bit before we can actually feed it to the LDAP server. Thus we'll edit it using (note the extra backslashes to escape the equal-sign and curly brackets):
root@easton2:/tmp# '''vi /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif'''
* We need to change and edit some parts of ''cn={4}samba.ldif'':
** Near the top we find ''dn: cn={4}samba''. We'll change this to the correct distinguished name ''dn: cn=samba,cn=schema,cn=config''
** Also near the top: ''cn: {4}samba''. We'll change this to ''cn: samba''
** The last seven lines look like the bit below - we need to remove these lines:
structuralObjectClass: olcSchemaConfig
entryUUID: f19250ba-1057-1031-88b7-8301a25f1d46
creatorsName: cn=config
createTimestamp: 20120401150603Z
entryCSN: 20120401150603.478495Z#000000#000#000000
modifiersName: cn=config
modifyTimestamp: 20120401150603Z
* We'll store the cleaned up LDIF file in ''/etc/ldap/schema'' with the originating schema file
root@easton2:/tmp# '''mv /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif /etc/ldap/schema/samba.ldif'''
root@easton2:/tmp# '''_'''
===Inserting the LDIF file in the LDAP server===
Time to actually invoke ''ldapadd'' which can put this schema in our LDAP server.
root@easton2:/tmp# '''ldapadd -QY EXTERNAL -H ldapi:/// -f /etc/ldap/schema/samba.ldif'''
adding new entry "cn=samba,cn=schema,cn=config"
root@easton2:/tmp# '''_'''

OpenSSH server

2016-02-21T15:17:51Z

Saruman!: /* Configuring PuTTy to use the SSH key */

==OpenSSH Server==

This package is essential when you want to be able to (safely) administer your server from another place than the console.

To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded.

After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'':
* line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]).
* add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''.
* Change your banner by editing the [[MOTD file]].

Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access:
groupadd -g 117 wheel
usermod -a -G wheel jan
In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users.

If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]]

When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''.

One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines.

== Changing RSA keys ==
Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this:
localhost:~# '''ssh insomnia@easton.saruman.biz'''
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the RSA host key has just been changed.
The fingerprint for the RSA key sent by the remote host is
f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12.
Please contact your system administrator.
Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message.
Offending key in /home/sixpacjo/.ssh/known_hosts:4
RSA host key for easton.saruman.biz has changed and you have requested strict checking.
Host key verification failed.
localhost:~# _
When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this:
Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5'
Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4
you should remove the RSA key for the IP number as well. This you do with the following two commands:
localhost:~# '''ssh-keygen -R easton.saruman.biz'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# '''ssh-keygen -R 192.168.67.5'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# _
After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file.

==Using SSH keys for SSH login==
If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSH keys to the mix.

What we're going to do is create an SSH key pair: a public key that we can store on the server, and a private key that we'll use on our end when we connect with the server.

===Generating an SSH key===
You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management.
(based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto])

First we start the PuTTyGen utility, by double-clicking on its .exe file.
* At the bottom of the interface, for Type of key to generate, select SSH-2 RSA;
* In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate);
* Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated;
* In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair;
* A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!)
The above actions should look a bit like this:

[[File:Puttygen.png|PuTTyGen interface]]

* Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content;
* Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk'''

===Putting the public key on the server===
To put the key on the server, we need to use not the public key ''file'', as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window - which is the public key, something like
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne
82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq
IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/
a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX
CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI
bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18
eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q
W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR
abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS
fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI
g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+
/pU0= Joe Sixpack
Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information.

On a side note, if you need the ''private'' key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar.

Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'':
cd /home/jsixpack/.ssh
touch authorized_keys
chmod 600 authorized_keys
Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':wq'' and the key is stored!

===Configuring the SSH server===

To ensure that the SSH server accepts SSH keys, add the following to ''/etc/ssh/sshd_config'', or at least confirm the lines are already there:
RSAAuthentication yes
PubkeyAuthentication yes
AuthorizedKeysFile %h/.ssh/authorized_keys
If you've changed any of these settings, restart the SSH server to ensure they're implemented. Then test if you can log in to the server with your SSH key (see next section).

Once you've ensured you can log into the server using only the key and it's associated passphrase, you may wish to disable password-based login. To configure the SSH server to ''not'' accept passwords any more, add the following (or confirm it's already set):
ChallengeResponseAuthentication no
PasswordAuthentication no
Again, restart the server if you've changed these settings. BEWARE! If you haven't properly tested logging in with a key, and you disable password-based login, then you've shut yourself out. Only access to the console can then restore your access...

===Configuring PuTTy to use the SSH key===
You've added your public key to the server, now add your private key to your PuTTy session information. To this end, put your private key in a secure spot accessible from your system. For example, on a secure (encrypted) USB stick. In this example I use a subdirectory of the Documents directory, named Keychain.
Now configure your PuTTy connection like you always would, but also go to the settings category Connection, subsection SSH, subsection Auth. There you'll find a Private key file section, from which you can browse to your .ppk private key file. It should look like this:
[[File:Puttyprivatekey.png|467px]]

Then go back to the Session category to get to the PuTTy "main" screen, and hit Save. That's it. You can now log on to your server using PuTTy, and when connecting Putty will ask for the passphrase, but not for any password local to the server.

OpenSSH server

2016-02-21T15:16:20Z

Saruman!: /* Configuring PuTTy to use the SSH key */

==OpenSSH Server==

This package is essential when you want to be able to (safely) administer your server from another place than the console.

To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded.

After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'':
* line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]).
* add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''.
* Change your banner by editing the [[MOTD file]].

Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access:
groupadd -g 117 wheel
usermod -a -G wheel jan
In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users.

If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]]

When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''.

One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines.

== Changing RSA keys ==
Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this:
localhost:~# '''ssh insomnia@easton.saruman.biz'''
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the RSA host key has just been changed.
The fingerprint for the RSA key sent by the remote host is
f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12.
Please contact your system administrator.
Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message.
Offending key in /home/sixpacjo/.ssh/known_hosts:4
RSA host key for easton.saruman.biz has changed and you have requested strict checking.
Host key verification failed.
localhost:~# _
When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this:
Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5'
Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4
you should remove the RSA key for the IP number as well. This you do with the following two commands:
localhost:~# '''ssh-keygen -R easton.saruman.biz'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# '''ssh-keygen -R 192.168.67.5'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# _
After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file.

==Using SSH keys for SSH login==
If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSH keys to the mix.

What we're going to do is create an SSH key pair: a public key that we can store on the server, and a private key that we'll use on our end when we connect with the server.

===Generating an SSH key===
You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management.
(based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto])

First we start the PuTTyGen utility, by double-clicking on its .exe file.
* At the bottom of the interface, for Type of key to generate, select SSH-2 RSA;
* In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate);
* Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated;
* In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair;
* A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!)
The above actions should look a bit like this:

[[File:Puttygen.png|PuTTyGen interface]]

* Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content;
* Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk'''

===Putting the public key on the server===
To put the key on the server, we need to use not the public key ''file'', as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window - which is the public key, something like
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne
82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq
IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/
a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX
CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI
bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18
eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q
W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR
abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS
fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI
g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+
/pU0= Joe Sixpack
Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information.

On a side note, if you need the ''private'' key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar.

Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'':
cd /home/jsixpack/.ssh
touch authorized_keys
chmod 600 authorized_keys
Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':wq'' and the key is stored!

===Configuring the SSH server===

To ensure that the SSH server accepts SSH keys, add the following to ''/etc/ssh/sshd_config'', or at least confirm the lines are already there:
RSAAuthentication yes
PubkeyAuthentication yes
AuthorizedKeysFile %h/.ssh/authorized_keys
If you've changed any of these settings, restart the SSH server to ensure they're implemented. Then test if you can log in to the server with your SSH key (see next section).

Once you've ensured you can log into the server using only the key and it's associated passphrase, you may wish to disable password-based login. To configure the SSH server to ''not'' accept passwords any more, add the following (or confirm it's already set):
ChallengeResponseAuthentication no
PasswordAuthentication no
Again, restart the server if you've changed these settings. BEWARE! If you haven't properly tested logging in with a key, and you disable password-based login, then you've shut yourself out. Only access to the console can then restore your access...

===Configuring PuTTy to use the SSH key===
You've added your public key to the server, now add your private key to your PuTTy session information. To this end, put your private key in a secure spot accessible from your system. For example, on a secure (encrypted) USB stick. In this example I use a subdirectory of the Documents directory, named Keychain.
Now configure your PuTTy connection like you always would, but also go to the settings category Connection, subsection SSH, subsection Auth. There you'll find a Private key file section, from which you can browse to your .ppk private key file. It should look like this:
[[File:Puttyprivatekey.png|467px]]

That's it. You can now log on to your server using PuTTy, and when connecting Putty will ask for the passphrase, but not for any password local to the server.

OpenSSH server

2016-02-21T15:16:05Z

Saruman!: /* Configuring PuTTy to use the SSH key */

==OpenSSH Server==

This package is essential when you want to be able to (safely) administer your server from another place than the console.

To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded.

After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'':
* line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]).
* add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''.
* Change your banner by editing the [[MOTD file]].

Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access:
groupadd -g 117 wheel
usermod -a -G wheel jan
In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users.

If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]]

When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''.

One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines.

== Changing RSA keys ==
Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this:
localhost:~# '''ssh insomnia@easton.saruman.biz'''
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the RSA host key has just been changed.
The fingerprint for the RSA key sent by the remote host is
f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12.
Please contact your system administrator.
Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message.
Offending key in /home/sixpacjo/.ssh/known_hosts:4
RSA host key for easton.saruman.biz has changed and you have requested strict checking.
Host key verification failed.
localhost:~# _
When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this:
Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5'
Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4
you should remove the RSA key for the IP number as well. This you do with the following two commands:
localhost:~# '''ssh-keygen -R easton.saruman.biz'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# '''ssh-keygen -R 192.168.67.5'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# _
After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file.

==Using SSH keys for SSH login==
If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSH keys to the mix.

What we're going to do is create an SSH key pair: a public key that we can store on the server, and a private key that we'll use on our end when we connect with the server.

===Generating an SSH key===
You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management.
(based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto])

First we start the PuTTyGen utility, by double-clicking on its .exe file.
* At the bottom of the interface, for Type of key to generate, select SSH-2 RSA;
* In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate);
* Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated;
* In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair;
* A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!)
The above actions should look a bit like this:

[[File:Puttygen.png|PuTTyGen interface]]

* Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content;
* Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk'''

===Putting the public key on the server===
To put the key on the server, we need to use not the public key ''file'', as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window - which is the public key, something like
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne
82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq
IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/
a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX
CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI
bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18
eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q
W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR
abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS
fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI
g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+
/pU0= Joe Sixpack
Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information.

On a side note, if you need the ''private'' key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar.

Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'':
cd /home/jsixpack/.ssh
touch authorized_keys
chmod 600 authorized_keys
Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':wq'' and the key is stored!

===Configuring the SSH server===

To ensure that the SSH server accepts SSH keys, add the following to ''/etc/ssh/sshd_config'', or at least confirm the lines are already there:
RSAAuthentication yes
PubkeyAuthentication yes
AuthorizedKeysFile %h/.ssh/authorized_keys
If you've changed any of these settings, restart the SSH server to ensure they're implemented. Then test if you can log in to the server with your SSH key (see next section).

Once you've ensured you can log into the server using only the key and it's associated passphrase, you may wish to disable password-based login. To configure the SSH server to ''not'' accept passwords any more, add the following (or confirm it's already set):
ChallengeResponseAuthentication no
PasswordAuthentication no
Again, restart the server if you've changed these settings. BEWARE! If you haven't properly tested logging in with a key, and you disable password-based login, then you've shut yourself out. Only access to the console can then restore your access...

===Configuring PuTTy to use the SSH key===
You've added your public key to the server, now add your private key to your PuTTy session information. To this end, put your private key in a secure spot accessible from your system. For example, on a secure (encrypted) USB stick. In this example I use a subdirectory of the Documents directory, named Keychain.
Now configure your PuTTy connection like you always would, but also go to the settings category Connection, subsection SSH, subsection Auth. There you'll find a Private key file section, from which you can browse to your .ppk private key file. It should look like this:
[[File:Puttyprivatekey.png|467px]]
That's it. You can now log on to your server using PuTTy, and when connecting Putty will ask for the passphrase, but not for any password local to the server.

File:Puttyprivatekey.png

2016-02-21T15:09:28Z

Saruman!: Example for PuTTy config

Example for PuTTy config

OpenSSH server

2015-12-16T15:28:57Z

Saruman!: typo's

Main Page

2015-09-04T19:07:05Z

Saruman!:

<big>'''Welcome to SaruWiki.'''</big>

This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site].

Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software.

<big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are.

----
<big>'''Main Content'''</big>

* Setting up a [[Debian Jessie base server|Debian 8 Jessie base server]] is a howto on the installation of a very basic Linux box under Jessie (it's actually not even a server yet).
* Using ''md'' and ''btrfs'' for [[software-based RAID]] contains our ideas and observations on data redundancy.
* The use of [[APT and aptitude]] is crucial to the concept of a Debian machine.
* [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it.
* [[Essential system software]] lists all (sets of) packages that we deem, well, essential.
* The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots.
* The [[networking section]] treats subjects like setting persistent routes.
* The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling.
* The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel.
* [[Hardware monitoring]] is important for your server's health and reliability.
* Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]].
* Creating a [[backup]] for your server.

'''Authentication and security'''
* [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it.
* [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository.
* [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them

'''Your own LAMP server'''
* [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]].
* [[Database 101]] introduces you to MySQL.

'''Other server apps'''
* The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend.
* [[Add an X11 server]] to your server, if you need one.
* Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP.
* The [[Asterisk section]] is about all things re: telephony on Debian Lenny.
* [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box.
* How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now.
* How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"])
* How to create [[your own ownCloud]] server (and here's [http://www.thecomputerkid.com/2013/06/why-you-should-use-owncloud.html why] you should do this)

----
If you'd like to create a new page, please log in and go ahead
'''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team.

Big Bag'o'utilities

2015-06-17T10:51:07Z

Saruman!: nicer layout

All utilities listed below are command line utilities; install them using ''apt-get install'' or ''aptitude''.

* ''apticron'' checks your system daily, and mails you when there are updates for packages
* ''ccze'' can "colorize" output, e.g. ''tail -f /var/log/syslog | ccze''
* ''[http://packages.debian.org/ethtool ethtool]'' can change settings for ethernet cards, like speed and duplex
* ''ipcalc'' is an IP address/mask calculator
* (''[[IProute | iproute]]'' helps viewing and setting the [http://lartc.org/ IP configuration] - under Lenny it's installed by default, under Etch you'll have to do it yourself)
* ''iptraf'' is an IP traffic monitor
* ''less'' is a utility [http://blog.platinumsolutions.com/node/47 to view text files];
* ''lsof'' can show all open files
* ''multitail'' can follow multiple (log)files in one terminal
* ''pwgen'' is a password generator
* ''[[Sudo | sudo]]'' enables you to execute commands with another user's credentials
* ''[[TCPdump | tcpdump]] is a network sniffer
* ''pciutils'' contains the ''lspci'' command, which can be useful to review your hardware
 
The following are compression and archiving tools:
* ''arj'' is a tool for the .arj file format
* ''bzip2'' is for .bz2 files
* ''p7zip'' is for .7z archives
* ''unzip'' is for the .zip file format
* ''xz-utils'' is a toolkit for LZ/M compression; adding it will make ''tar'' understand .xz files
* ''zoo'' is for the .zoo file format

Big Bag'o'utilities

2015-06-17T10:48:45Z

Saruman!: added p7zip and xz-utils

All utilities listed below are command line utilities; install them using ''apt-get install'' or ''aptitude''.

''apticron'' checks your system daily, and mails you when there are updates for packages 
''ccze'' can "colorize" output, e.g. ''tail -f /var/log/syslog | ccze'' 
''[http://packages.debian.org/ethtool ethtool]'' can change settings for ethernet cards, like speed and duplex 
''ipcalc'' is an IP address/mask calculator 
(''[[IProute | iproute]]'' helps viewing and setting the [http://lartc.org/ IP configuration] - under Lenny it's installed by default, under Etch you'll have to do it yourself) 
''iptraf'' is an IP traffic monitor 
''less'' is a utility [http://blog.platinumsolutions.com/node/47 to view text files]; 
''lsof'' can show all open files 
''multitail'' can follow multiple (log)files in one terminal 
''pwgen'' is a password generator 
''[[Sudo | sudo]]'' enables you to execute commands with another user's credentials 
''[[TCPdump | tcpdump]] is a network sniffer 
''pciutils'' contains the ''lspci'' command, which can be useful to review your hardware 

The following are compression and archiving tools:
''arj'' is a tool for the .arj file format 
''bzip2'' is for .bz2 files 
''p7zip'' is for .7z archives 
''unzip'' is for the .zip file format 
''xz-utils'' is a toolkit for LZ/M compression; adding it will make ''tar'' understand .xz files 
''zoo'' is for the .zoo file format

Main Page

2015-06-16T20:16:42Z

Saruman!: text

<big>'''Welcome to SaruWiki.'''</big>

This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site].

Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software.

<big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are.

----
<big>'''Main Content'''</big>

* Setting up a [[Debian Jessie base server]] is a howto on the installation of a very basic Linux box under Jessie (it's actually not even a server yet).
* Using ''md'' and ''btrfs'' for [[software-based RAID]] contains our ideas and observations on data redundancy.
* The use of [[APT and aptitude]] is crucial to the concept of a Debian machine.
* [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it.
* [[Essential system software]] lists all (sets of) packages that we deem, well, essential.
* The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots.
* The [[networking section]] treats subjects like setting persistent routes.
* The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling.
* The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel.
* [[Hardware monitoring]] is important for your server's health and reliability.
* Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]].
* Creating a [[backup]] for your server.

'''Authentication and security'''
* [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it.
* [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository.
* [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them

'''Your own LAMP server'''
* [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]].
* [[Database 101]] introduces you to MySQL.

'''Other server apps'''
* The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend.
* [[Add an X11 server]] to your server, if you need one.
* Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP.
* The [[Asterisk section]] is about all things re: telephony on Debian Lenny.
* [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box.
* How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now.
* How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"])
* How to create [[your own ownCloud]] server (and here's [http://www.thecomputerkid.com/2013/06/why-you-should-use-owncloud.html why] you should do this)

----
If you'd like to create a new page, please log in and go ahead
'''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team.

Main Page

2015-06-16T20:10:39Z

Saruman!: link to Jessie server

<big>'''Welcome to SaruWiki.'''</big>

This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site].

Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software.

<big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are.

----
<big>'''Main Content'''</big>

* Setting up a [[Debian_Jessie_base_server]] is a howto on the installation of a very basic Linux box under Jessie (it's actually not even a server yet).
* Using ''md'' for [[software-based RAID]] contains our ideas and observations on redundancy.
* The use of [[APT and aptitude]] is crucial to the concept of a Debian machine.
* [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it.
* [[Essential system software]] lists all (sets of) packages that we deem, well, essential.
* The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots.
* The [[networking section]] treats subjects like setting persistent routes.
* The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling.
* The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel.
* [[Hardware monitoring]] is important for your server's health and reliability.
* Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]].
* Creating a [[backup]] for your server.

'''Authentication and security'''
* [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it.
* [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository.
* [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them

'''Your own LAMP server'''
* [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]].
* [[Database 101]] introduces you to MySQL.

'''Other server apps'''
* The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend.
* [[Add an X11 server]] to your server, if you need one.
* Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP.
* The [[Asterisk section]] is about all things re: telephony on Debian Lenny.
* [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box.
* How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now.
* How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"])
* How to create [[your own ownCloud]] server (and here's [http://www.thecomputerkid.com/2013/06/why-you-should-use-owncloud.html why] you should do this)

----
If you'd like to create a new page, please log in and go ahead
'''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team.

Debian Jessie base server

2015-06-16T20:09:51Z

Saruman!: branched off of old Wheezy base server page

__TOC__

==Hardware preparation==
When installing a new server, you must begin with [[Server hardware prep|getting your server hardware right]]. Assuming you've built yourself a new server platform, you can install the operating system following the steps outlined below. Note: it is assumed the server is bare, and the hard disks are completely clean. If they are not, here's how to [[Cleaning a hard disk|clean]] them.

==Planning your network names==
If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[https://kb.isc.org/article/AA-01031 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system.
Here is our tip on choosing a DNS domain for your home network:
* do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet;
* for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN)
* for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan".
This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network.
OK, with this out of the way, we can get to installing the OS.

==Operating System installation==
===Preparing to boot into the installer===
To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - as of april 2015, it's Debian 8, or "Jessie" as it's also known.

Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [https://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time.

In the example at hand we're installing on an Intel Atom C2000-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/debian-cd/8.1.0/amd64/iso-cd/debian-8.1.0-amd64-netinst.iso debian-8.1.0-amd64-netinst.iso], which is Jessie after its first update. If you wish, you can burn this to a CD-recordable and boot your prepared hardware platform from this CD. As it stands, we can boot our server platform from the iso file directly by sharing the image using SaMBa, then mounting that fileshared image in the server hardware console - we're lucky that way not needing physical CDs :-)

===Installer===
After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are:
* Install, the default non-graphical installation;
* Graphical install, so you can click things;
* Advanced options, where you can select expert options like the rescue mode;
* Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer).
We're going to use the standard Command Line installation, so we choose "Install" and hit <enter>.
{| class="wikitable" border="1" |-
|We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and Real Men Don't Click. Also, we've found that from the GUI it's a bit harder to switch to a second console and then back.
We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do just fine without the barrage of extra questions that the "expert" installation method pose.
|}

After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices:
* Language: English
* country: other > Europe > Netherlands
* locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8
* keymap: American English (since we have a keyboard with US layout)
Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC.
{| class="wikitable" border="1" |-
|Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an ancient 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine.
|}
Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network configuration manually, or fix your DHCP-server and connection between it and ''eth0''.

Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips:
* do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear);
* do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning);
* do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine);
* do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location);
* do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accommodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650).
What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001".

Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press <enter>.

Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [https://identitysafe.norton.com/password-generator/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!).

Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password.

After entering the details of these two users "root" and "you", we get to the server hardware.

===Partitioning===
Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions.
To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed.

So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]] is this:
{| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5"
!style="background:#ffdead;"|Partition
!style="background:#ffdead;"|MD
!style="background:#ffdead;"|LVG
!style="background:#ffdead;"|LV-name
!style="background:#ffdead;"|Size (physical machine)
!style="background:#ffdead;"|Size (VM)
!style="background:#ffdead;"|File System
!style="background:#ffdead;"|Mount point
|-
| 1
| /dev/md0
|  
|  
| 100MiB
| 100MiB
| ext3
| /boot
|-
| 2
| /dev/md1
|  
|  
| 3GiB
| 1GiB
| ext3
| /
|-
| rowspan="8" valign="top" | 3
| rowspan="8" valign="top" | /dev/md2
| rowspan="8" valign="top" style="background:lightgrey"| system
| style="background:lightgrey" | swap
| 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref>
| 256MiB<ref name="swap"/>
| swap
|  
|-
| style="background:lightgrey" | var
| 1GiB
| 512MiB
| ext3
| /var
|-
| style="background:lightgrey" | varlog
| 1GiB
| 512MiB
| ext3
| /var/log
|-
| style="background:lightgrey" | appslog
| 3GiB
| -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref>
| ext3
| /var/appslog
|-
| style="background:lightgrey" | home
| 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref>
| 512MiB<ref name="home"/>
| ext3
| /home
|-
| style="background:lightgrey" | usr
| 3GiB
| 3GiB
| ext3
| /usr
|-
| style="background:lightgrey" | tmp
| 1GiB
| 512MiB
| ext3
| /tmp
|-
| style="background:lightgrey" | opt
| 1GiB
| -
| ext3
| /opt
|-
! colspan="4" style="text-align:right"| Total
! 18.1GiB
! 6.9GiB
! colspan="2" |
|-
|}

As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/vsphere VMware Server] or something alike, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives.

Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitioning options, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions).

<references/>

===Software RAID partitioning===
If you're to use software RAID, you now have to select the free space on the first drive, press <enter>, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition".

Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?).

Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk.

If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks.

Now you can create RAID devices. The RAID levels that Debian 6.0 offer are 0 (striping), 1 (mirroring), 5 (distributed redundancy), 6 (double distributed redundancy) ant 10 (striped mirrors). For your operating system disk pair, level 1 is the only sane choice.

When selecting RAID 1, the installer asks how many active devices to use (2), how many spares (0), and then offers a selection screen where you can mark all members of the array. Select the first partition of both disks (presumably ''/dev/sda1'' and ''/dev/sdb1'') which should correspond to the 100MiB partitions you've created. Then create the other MD devices. Finally, choose <finish>. You'll drop back to the partitioner, but now the three created devices are available in the partitioner as "RAID1 device #0" etc.

===Hardware RAID partitioning===
Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner:

Select the free space on the intended boot disk, press <enter>, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition".

The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition".

The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more.

==Logical Volume creation==
We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. To this end, in the volume group creation dialogue, we select that partition (''/dev/md2''). Note that all other selection choices are either unusable (unusable free space) or assigned to other purposes (/boot and /).

Now we repeat the following process seven times:
* select "Create Logical Volume"
* select Volume Group "System"
* give the LV Name (from the table, e.g. swap, var etc)
* give the LV size (from the table, e.g. 1GB for swap etc)

After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.0GB Linux device mapper (linear)''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process:
* select the unassigned chunk of empty space of an LV (e.g. ''appslog'') and press <enter>;
* Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area");
* Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog" and varlog as "/var/log");
* If so desired, a label can be assigned to the partition (we usually don't);
* select "Done setting up the partition".

Note that sometimes, after creating and assigning the logical volumes, the installer has forgotten to mount the md0 and md1 partitions as /boot and /. In that case you'll have to reassign these partitions to these points in the filesystem.

Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues.

==Base system setup==
Now the Debian installer loads a base system. It will scan your installation CD/DVD, and ask if it should scan more CD/DVDs. We're going with "no" here. Then it will ask you how it can contact the Debian archives, in the dialogue "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has successfully been contacted when it's saying "Retrieving file 1 of 5". A number of files are retrieved, and the base system is set up. Somewhere early in this setup, the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please.
And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently:
* Graphical desktop environment
* Web server
* Print server
* DNS server
* File server
* Mail server
* SQL database
* SSH server
* Laptop
* Standard system utilities (selected by default)
We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you're like us: deselect the "Standard system utilities" entry, and select Continue.

The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes".

After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Squeeze. Remove the CD and select "Continue"

==Finishing up the installation==
The system should reboot into Debian. This means you should see the following boot sequence:
* your machine's standard POST messages
* briefly a '''welcome to GRUB''' message
* then, a blue grub menu on a black screen, with two entries:
** Debian GNU/Linux, with Linux 2.6.32-5-686
** Debian GNU/Linux, with Linux 2.6.32-5-686 (recovery mode)
* then, after a default (short!) time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read:
Debian GNU/Linux 6.0 easton2 tty1
easton2 login: '''_'''
If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem.

Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version.

Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favourite commands are always available.

OpenSSH server

2014-10-26T20:32:47Z

Saruman!: typos

==OpenSSH Server==

This package is essential when you want to be able to (safely) administer your server from another place than the console.

To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded.

After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'':
* line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]).
* add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''.
* Change your banner by editing the [[MOTD file]].

Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access:
groupadd -g 117 wheel
usermod -a -G wheel jan
In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users.

If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]]

When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''.

One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines.

== Changing RSA keys ==
Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this:
localhost:~# '''ssh insomnia@easton.saruman.biz'''
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the RSA host key has just been changed.
The fingerprint for the RSA key sent by the remote host is
f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12.
Please contact your system administrator.
Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message.
Offending key in /home/sixpacjo/.ssh/known_hosts:4
RSA host key for easton.saruman.biz has changed and you have requested strict checking.
Host key verification failed.
localhost:~# _
When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this:
Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5'
Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4
you should remove the RSA key for the IP number as well. This you do with the following two commands:
localhost:~# '''ssh-keygen -R easton.saruman.biz'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# '''ssh-keygen -R 192.168.67.5'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# _
After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file.

==Using SSH keys for SSH login==
If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSH keys to the mix.

===Generating an SSH key===
You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management.
(based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto])

First we start the PuTTyGen utility, by double-clicking on its .exe file.
* At the bottom of the interface, for Type of key to generate, select SSH-2 RSA;
* In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate);
* Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated;
* In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair;
* A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!)
The above actions should look a bit like this:

[[File:Puttygen.png|PuTTyGen interface]]

* Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content;
* Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk'''

===Putting the key on the server===
To put the key on the server, we need to use not the public key file, as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window, something like
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne
82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq
IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/
a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX
CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI
bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18
eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q
W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR
abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS
fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI
g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+
/pU0= Joe Sixpack
Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information.

On a sidenote, if you need the private key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar.

Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'':
cd /home/jsixpack/.ssh
touch authorized_keys
chmod 600 authorized_keys
Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':qw'' and the key is stored!

===Configuring the SSH server===

To ensure that the SSH server accepts SSH keys, add the following to ''/etc/ssh/sshd_config'', or at least confirm the lines are already there:
RSAAuthentication yes
PubkeyAuthentication yes
AuthorizedKeysFile %h/.ssh/authorized_keys
If you've changed any of these settings, restart the SSH server to ensure they're implemented. Then test if you can log in to the server with your SSH key (see next session).

Once you've ensured you can log into the server using only the key and it's associated passphrase, you may wish to disable password-based login. To configure the SSH server to ''not'' accept passwords any more, add the following (or confirm it's already set):
ChallengeResponseAuthentication no
PasswordAuthentication no
Again, restart the server if you've changed these settings. BEWARE! If you haven't properly tested logging in with a key, and you disable password-based login, then you've shut yourself out. Only access to the console can then restore your access...

===Configuring PuTTy to use the SSH key===
You've added your public key to the server, now add your private key to your PuTTy session information.

OpenSSH server

2014-10-26T20:29:55Z

Saruman!: ssh server config

==OpenSSH Server==

This package is essential when you want to be able to (safely) administer your server from another place than the console.

To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded.

After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'':
* line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]).
* add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''.
* Change your banner by editing the [[MOTD file]].

Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access:
groupadd -g 117 wheel
usermod -a -G wheel jan
In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users.

If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]]

When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''.

One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines.

== Changing RSA keys ==
Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this:
localhost:~# '''ssh insomnia@easton.saruman.biz'''
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the RSA host key has just been changed.
The fingerprint for the RSA key sent by the remote host is
f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12.
Please contact your system administrator.
Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message.
Offending key in /home/sixpacjo/.ssh/known_hosts:4
RSA host key for easton.saruman.biz has changed and you have requested strict checking.
Host key verification failed.
localhost:~# _
When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this:
Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5'
Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4
you should remove the RSA key for the IP number as well. This you do with the following two commands:
localhost:~# '''ssh-keygen -R easton.saruman.biz'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# '''ssh-keygen -R 192.168.67.5'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# _
After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file.

==Using certificates for SSH login==
If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSL keys to the mix.

===Generating an SSH key===
You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management.
(based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto])

First we start the PuTTyGen utility, by double-clicking on its .exe file.
* At the bottom of the interface, for Type of key to generate, select SSH-2 RSA;
* In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate);
* Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated;
* In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair;
* A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!)
The above actions should look a bit like this:

[[File:Puttygen.png|PuTTyGen interface]]

* Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content;
* Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk'''

===Putting the key on the server===
To put the key on the server, we need to use not the public key file, as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window, something like
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne
82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq
IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/
a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX
CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI
bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18
eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q
W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR
abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS
fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI
g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+
/pU0= Joe Sixpack
Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information.

On a sidenote, if you need the private key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar.

Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'':
cd /home/jsixpack/.ssh
touch authorized_keys
chmod 600 authorized_keys
Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':qw'' and the key is stored!

===Configuring the SSH server===

To ensure that the SSH server accepts SSH keys, add the following to ''/etc/ssh/sshd_config'', or at least confirm the lines are already there:
RSAAuthentication yes
PubkeyAuthentication yes
AuthorizedKeysFile %h/.ssh/authorized_keys
If you've changed any of these settings, restart the SSH server to ensure they're implemented. Then test if you can log in to the server with your SSH key (see next session).

Once you've ensured you can log into the server using only the key and it's associated passphrase, you may wish to disable password-based login. To configure the SSH server to ''not'' accept passwords any more, add the following (or confirm it's already set):
ChallengeResponseAuthentication no
PasswordAuthentication no
Again, restart the server if you've changed these settings. BEWARE! If you haven't properly tested logging in with a key, and you disable password-based login, then you've shut yourself out. Only access to the console can then restore your access...

===Configuring PuTTy to use the SSH key===
You've added your public key to the server, now add your private key to your PuTTy session information.

OpenSSH server

2014-10-26T20:06:57Z

Saruman!: intermediate save

==OpenSSH Server==

This package is essential when you want to be able to (safely) administer your server from another place than the console.

To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded.

After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'':
* line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]).
* add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''.
* Change your banner by editing the [[MOTD file]].

Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access:
groupadd -g 117 wheel
usermod -a -G wheel jan
In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users.

If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]]

When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''.

One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines.

== Changing RSA keys ==
Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this:
localhost:~# '''ssh insomnia@easton.saruman.biz'''
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the RSA host key has just been changed.
The fingerprint for the RSA key sent by the remote host is
f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12.
Please contact your system administrator.
Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message.
Offending key in /home/sixpacjo/.ssh/known_hosts:4
RSA host key for easton.saruman.biz has changed and you have requested strict checking.
Host key verification failed.
localhost:~# _
When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this:
Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5'
Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4
you should remove the RSA key for the IP number as well. This you do with the following two commands:
localhost:~# '''ssh-keygen -R easton.saruman.biz'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# '''ssh-keygen -R 192.168.67.5'''
/home/sixpacjo/.ssh/known_hosts updated.
Original contents retained as /home/sixpacjo/.ssh/known_hosts.old
localhost:~# _
After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file.

==Using certificates for SSH login==
If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSL keys to the mix.

===Generating an SSH key===
You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management.
(based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto])

First we start the PuTTyGen utility, by double-clicking on its .exe file.
* At the bottom of the interface, for Type of key to generate, select SSH-2 RSA;
* In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate);
* Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated;
* In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair;
* A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!)
The above actions should look a bit like this:

[[File:Puttygen.png|PuTTyGen interface]]

* Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content;
* Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk'''

===Putting the key on the server===
To put the key on the server, we need to use not the public key file, as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window, something like
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne
82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq
IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/
a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX
CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI
bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18
eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q
W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR
abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS
fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI
g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+
/pU0= Joe Sixpack
Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information.

On a sidenote, if you need the private key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar.

Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'':
cd /home/jsixpack/.ssh
touch authorized_keys
chmod 600 authorized_keys
Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':qw'' and the key is stored!

===Configuring the SSH server===

File:Puttygen.png

2014-10-26T19:59:12Z

Saruman!: Saruman! uploaded a new version of "File:Puttygen.png": correct example username

PuttyGen interface

OpenSSH server

2014-10-26T10:45:38Z

Saruman!: start ssh key section

File:Puttygen.png

2014-10-26T10:30:21Z

Saruman!: PuttyGen interface

PuttyGen interface

Your own ownCloud

2014-02-10T14:20:21Z

Saruman!: fixed ToC

<big>'''ownCloud'''</big>
In this day and age where many people are more and more dependant on information, cloud technology offers a way to unlock your information to you, wherever you are, on most any device. However, there's no telling what the cloud companies that you entrust with your information will do with that info - let alone nosy intelligence agencies from various countries around the world. My privacy [https://chronicle.com/article/Why-Privacy-Matters-Even-if/127461/ matters to me]!

'''[http://owncloud.org/ ownCloud]''' is a free and open source alternatives for many cloud offerings such as Google Drive and DropBox, as it gives you the ability to share and sync files from your own server, but it does [http://owncloud.org/features/ much more] - added bonus, I say...

___TOC___
==Introduction==
ownCloud broadly comes in two flavours: the open source, free "community edition" and the open source, paid "enterprise edition". We're going to install the community edition here. The goal will be to have a way to share files between groups of people, most of which will have an account on our server.

==Installing ownCloud==
In the following we're going to install ownCloud manually, that is to say we're not going to use any Linux package manager such as Debian's [https://wiki.debian.org/Apt apt] or Red Hat/CentOS's [https://access.redhat.com/site/solutions/9934 yum], but we're going to manually put the necessary files on the server. This has the advantage of being able to use the very latest & greatest version of ownCloud, but the disadvantage requiring us to do the heavy lifting, install-wise as well as update-wise. However, as we'll see below, a manual installation takes relatively little effort.

===Preparing your server===
First off we have to ensure that our server complies with ownCloud's requirements, as shown in the [http://doc.owncloud.org/server/6.0/admin_manual/installation/installation_source.html administrator manual]. This means we'll require a working LAMP server with a sufficient recent version of PHP, MySQL and Apache. If we want to secure our ownCloud communications using SSL, we also need to have a good SSL certificate (preferably not a self-signed one as many applications choke on that signature) and have set up our Apache server to correctly use it. Furthermore, ownCloud needs the Apache module mod-rewrite; usually one can enable it with a command such as ''a2enmod rewrite''.

===Getting ownCloud files on your server===
Now we'll choose a directory in which the ownCloud files can live; as it's a manual package, the Linux Standards Base ([http://www.linuxfoundation.org/collaborate/workgroups/lsb LSB]) suggests it goes into ''/opt''. We thus create the directory ''/opt/owncloud''. Next up we download the ownCloud ''tar.bz2'' file from the [http://owncloud.org/install/ ownCloud download page] to a temporary directory and extract it; this could look like
cd /tmp
wget http://download.owncloud.org/community/owncloud-6.0.1.tar.bz2
tar -xjf owncloud-6.0.1.tar.bz2
Note that the extraction causes the tree of ownCloud files to appear in a directory called ''owncloud''. Strictly speaking you could extract the file directly in /opt without first creating an ''owncloud'' directory by hand. However I like to keep an eye on processes like this. We can now move all the files from the tar into the prepared directory with a command such as
cp -pR /tmp/owncloud/* /opt/owncloud
Here please note that all files in the tar file are owned by a user with UID and GID 65534, corresponding with ''nobody:nogroup''. If your server or webserver setup require a different user/group, you should use ''chown'' to set this.

===Publishing ownCloud in Apache2===
As we would like all files pertaining to the configuration of our server to live under ''/etc'', we create a directory ''/etc/owncloud''. Now, in this directory we'll create a file named ''apache.conf'' containing
Alias /cloud /opt/owncloud
<Directory /opt/owncloud>
Options Indexes FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
allow from all
</Directory>
Publishing the ownCloud instance is now as easy as including this file in the relevant Apache (SSL) site configuration file. Under Debian, this means selecting the right file under ''/etc/apache2/sites-available/'' and insert the line
Include /etc/owncloud/apache.conf
If you now reload Apache with a command such as ''service apache2 reload'', you'll be able to surf to the URL of the pertaining site (e.g. https://www.saruman.biz/owncloud) and verify that the unconfigured owncloud instance is now accessible.

==Configuring ownCloud==
===Initial setup===
We'll need '''a data directory''' for ownCloud. My recommendation is something like ''/data/owncloud'', and since the web server is required to manipulate files in this directory, we'll make it owned by Debian's webserver user/group ''www-data:www-data'' (under other distributions, make sure to use the corresponding user/group). For this directory to be used by ownCloud, we'll symlink to it from ''/opt/owncloud'' with command:
ln -s /data/owncloud /opt/owncloud/data

We'll also need '''a database''' for ownCloud. To create one, we can start the MySQL client (''mysql -u root -p'' and then the password) and create a database plus database user using
mysql> create database owncloud;
mysql> create user 'ownclouduser'@'localhost' identified by '<password1>';
mysql> grant all on owncloud.* to 'ownclouduser'@'localhost';

Now we can surf to the ownCloud instance page, and we'll find the startscreen asking for setup details. Provided the following details:
* Admin account: '''owncloudadmin/<password2>'''
* Data folder: '''/opt/owncloud/data'''
* Database user: '''ownclouduser/<password1>'''
* Database name: '''owncloud'''
* Database host: '''localhost'''
Once we've finished the installation wizard, we'll be able to log in to ownCloud using the admin account (here ''owncloudadmin'') and the corresponding password.

If logging in works, then the following action will complete the configuration according to the LSB. We'll move the file ''/opt/owncloud/config/config.php'' that the installation wizard has created to our directory ''/etc/owncloud'' (if you like, you can also move the example configuration file ''config.sample.php'' for future reference). Then we symlink to it using
ln -s /etc/owncloud/config.php /opt/owncloud/config/config.php

===Using OpenLDAP as a backend===
===Theming ownCloud===

Your own ownCloud

2014-02-10T14:19:30Z

Saruman!: /* Installing ownCloud */ fleshed out

<big>'''ownCloud'''</big>
In this day and age where many people are more and more dependant on information, cloud technology offers a way to unlock your information to you, wherever you are, on most any device. However, there's no telling what the cloud companies that you entrust with your information will do with that info - let alone nosy intelligence agencies from various countries around the world. My privacy [https://chronicle.com/article/Why-Privacy-Matters-Even-if/127461/ matters to me]!

'''[http://owncloud.org/ ownCloud]''' is a free and open source alternatives for many cloud offerings such as Google Drive and DropBox, as it gives you the ability to share and sync files from your own server, but it does [http://owncloud.org/features/ much more] - added bonus, I say...

___TOC___
==Introduction==
ownCloud broadly comes in two flavours: the open source, free "community edition" and the open source, paid "enterprise edition". We're going to install the community edition here. The goal will be to have a way to share files between groups of people, most of which will have an account on our server.

==Installing ownCloud==
In the following we're going to install ownCloud manually, that is to say we're not going to use any Linux package manager such as Debian's [https://wiki.debian.org/Apt apt] or Red Hat/CentOS's [https://access.redhat.com/site/solutions/9934 yum], but we're going to manually put the necessary files on the server. This has the advantage of being able to use the very latest & greatest version of ownCloud, but the disadvantage requiring us to do the heavy lifting, install-wise as well as update-wise. However, as we'll see below, a manual installation takes relatively little effort.

===Preparing your server===
First off we have to ensure that our server complies with ownCloud's requirements, as shown in the [http://doc.owncloud.org/server/6.0/admin_manual/installation/installation_source.html administrator manual]. This means we'll require a working LAMP server with a sufficient recent version of PHP, MySQL and Apache. If we want to secure our ownCloud communications using SSL, we also need to have a good SSL certificate (preferably not a self-signed one as many applications choke on that signature) and have set up our Apache server to correctly use it. Furthermore, ownCloud needs the Apache module mod-rewrite; usually one can enable it with a command such as ''a2enmod rewrite''.

===Getting ownCloud files on your server===
Now we'll choose a directory in which the ownCloud files can live; as it's a manual package, the Linux Standards Base ([http://www.linuxfoundation.org/collaborate/workgroups/lsb LSB]) suggests it goes into ''/opt''. We thus create the directory ''/opt/owncloud''. Next up we download the ownCloud ''tar.bz2'' file from the [http://owncloud.org/install/ ownCloud download page] to a temporary directory and extract it; this could look like
cd /tmp
wget http://download.owncloud.org/community/owncloud-6.0.1.tar.bz2
tar -xjf owncloud-6.0.1.tar.bz2
Note that the extraction causes the tree of ownCloud files to appear in a directory called ''owncloud''. Strictly speaking you could extract the file directly in /opt without first creating an ''owncloud'' directory by hand. However I like to keep an eye on processes like this. We can now move all the files from the tar into the prepared directory with a command such as
cp -pR /tmp/owncloud/* /opt/owncloud
Here please note that all files in the tar file are owned by a user with UID and GID 65534, corresponding with ''nobody:nogroup''. If your server or webserver setup require a different user/group, you should use ''chown'' to set this.

===Publishing ownCloud in Apache2===
As we would like all files pertaining to the configuration of our server to live under ''/etc'', we create a directory ''/etc/owncloud''. Now, in this directory we'll create a file named ''apache.conf'' containing
Alias /cloud /opt/owncloud
<Directory /opt/owncloud>
Options Indexes FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
allow from all
</Directory>
Publishing the ownCloud instance is now as easy as including this file in the relevant Apache (SSL) site configuration file. Under Debian, this means selecting the right file under ''/etc/apache2/sites-available/'' and insert the line
Include /etc/owncloud/apache.conf
If you now reload Apache with a command such as ''service apache2 reload'', you'll be able to surf to the URL of the pertaining site (e.g. https://www.saruman.biz/owncloud) and verify that the unconfigured owncloud instance is now accessible.

==Configuring ownCloud==
We'll need '''a data directory''' for ownCloud. My recommendation is something like ''/data/owncloud'', and since the web server is required to manipulate files in this directory, we'll make it owned by Debian's webserver user/group ''www-data:www-data'' (under other distributions, make sure to use the corresponding user/group). For this directory to be used by ownCloud, we'll symlink to it from ''/opt/owncloud'' with command:
ln -s /data/owncloud /opt/owncloud/data

We'll also need '''a database''' for ownCloud. To create one, we can start the MySQL client (''mysql -u root -p'' and then the password) and create a database plus database user using
mysql> create database owncloud;
mysql> create user 'ownclouduser'@'localhost' identified by '<password1>';
mysql> grant all on owncloud.* to 'ownclouduser'@'localhost';

Now we can surf to the ownCloud instance page, and we'll find the startscreen asking for setup details. Provided the following details:
* Admin account: '''owncloudadmin/<password2>'''
* Data folder: '''/opt/owncloud/data'''
* Database user: '''ownclouduser/<password1>'''
* Database name: '''owncloud'''
* Database host: '''localhost'''
Once we've finished the installation wizard, we'll be able to log in to ownCloud using the admin account (here ''owncloudadmin'') and the corresponding password.

If logging in works, then the following action will complete the configuration according to the LSB. We'll move the file ''/opt/owncloud/config/config.php'' that the installation wizard has created to our directory ''/etc/owncloud'' (if you like, you can also move the example configuration file ''config.sample.php'' for future reference). Then we symlink to it using
ln -s /etc/owncloud/config.php /opt/owncloud/config/config.php

==Configuring ownCloud==
===Initial setup===
===Using OpenLDAP as a backend===
===Theming ownCloud===

E-mail server section

2014-02-04T20:58:37Z

Saruman!: /* E-mail server setup */ updated link to source article

==E-mail server setup==
What we want to accomplish here is the setup of a mail server with the following properties:
* can serve multiple mail domains
* can relay mail for other domains to other mail servers
* can have one or more mailboxes per domain
* users of these mailboxes can be virtual (do not need to have a Linux user account)
* can have multiple aliases per mailbox
* can forward mail for certain aliases to multiple mailboxes
For this type of mail server setup, we owe a great thankyou to [https://workaround.org/ispmail/squeeze Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003.

==Preparation==
We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems.

The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server.

The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail.

==Software installation==
As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is:
* ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol
At the same time we can - and must - purge the following packages:
* exim4
* exim4-base
* exim4-daemon-light
* exim4-config
In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix.

When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this:
* General type of mail configuration: Internet site
* System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting <enter>!
* Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster".
* Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this:
saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost
* Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself
* Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range)
* Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit.
* Character for local address extension: we leave it at ''+''
* Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only.
With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings.

Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well):
* ''postfix-doc'', the accompanying documentation;
* ''postfix-mysql'', necessary to have Postfix talk to our MySQL server;
* ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam;
* ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail;
* ''dovecot-pop3d'' is another daemon, but for the POP3 protocol.

==Virtual Mailman creation==
When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz).

To create this user, and his home directory, we can run the following commands:
groupadd -g 120 vmail
useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false
As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry.

To tell Postfix that this ''vmail'' user is someone special, we run
postconf -e virtual_uid_maps=static:120
postconf -e virtual_gid_maps=static:120
That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's.

==MySQL configuration==

===Database preparation===
We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this:
mysql -u root -p < create.vmail.sql
(This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view. 
A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly.

===Inserting data===
Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this:
mysql -u root -p vmail
mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz');
mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz');
mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz');
This has the effect of creating three entries. You can check that everything worked as planned by executing
mysql> select * from virtual_domains;
Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two.

Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section.

Whle still within the mysql client, we can now create users:
mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret'));
mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret'));
mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret'));
This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''.

The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works:
mysql> select * from virtual_users;
mysql> select * from view_users;

Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain".
mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination)
VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz');
mysql> INSERT INTO virtual_aliases (domain_id, source, destination)
VALUES (2, 'webmaster', 'j.doe@example.com');
mysql> INSERT INTO virtual_aliases (domain_id, destination)
VALUES (1, 'mike@saruman.biz');
mysql> INSERT INTO virtual_aliases (domain_id, destination)
VALUES (2, 'mike@saruman.biz');
mysql> INSERT INTO virtual_aliases (domain_id, destination)
VALUES (3, 'webmaster@saruman.biz');

Again, we don't need to add the ''id'' value any more after the first ever insertion into this table.

We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view:
mysql> select * from virtual_aliases;
mysql> select * from view_aliases;

== Postfix configuration for MySQL lookups==
Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases.

===Virtual mail domains lookup===

Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content:
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT 1 FROM virtual_domains WHERE vdomain='%s'
Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains":
postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf
Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret".

=== Virtual mail user lookup===
Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content:
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT 1 FROM view_users WHERE email='%s'
Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping:
postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf
The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e.
postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf
should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration.

=== Virtual alias lookup===
Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'':
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT destination FROM view_aliases WHERE email='%s'
And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'':
user = vmail_admin
password = SuperSecret
hosts = 127.0.0.1
dbname = vmail
query = SELECT email FROM view_users WHERE email='%s'

Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping:
postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf
The lookup of virtual aliases should now work as designed:
postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf
postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf
If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper.

===Finishing up configuration files===
When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus:
chown root:postfix /etc/postfix/mysql-*.cf
chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf
This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all.

==Configuring mail delivery through Dovecot LDA==
E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA.
===Enabling the Dovecot daemon===
To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'':
dovecot unix - n n - - pipe
flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient}
This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable:
postfix reload
postconf -e virtual_transport=dovecot
postconf -e dovecot_destination_recipient_limit=1
===Dovecot default configuration===
Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads
protocols = imap imaps pop3 pop3s
(which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#mail_location ='', and change it to
mail_location = maildir:/data/vmail/%d/%n/Maildir
This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format.
Next look for a section called "auth default". First define the allowed authentication mechanisms:
mechanisms = plain login
Then inside that same section you need to uncomment:
passdb sql {
args = /etc/dovecot/dovecot-sql.conf
}
which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and:
userdb static {
args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes
}
to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well.

Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is
namespace private {
separator = .
prefix =
inbox = yes
}
However, your mileage may vary.

You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users.

Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section):
socket listen {
master {
path = /var/run/dovecot/auth-master
mode = 0600
user = vmail
}
client {
path = /var/spool/postfix/private/auth
mode = 0660
user = postfix
group = postfix
}
}

Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts:
protocol lda {
log_path = /var/log/appslog/mail/dovecot-deliver.log
auth_socket_path = /var/run/dovecot/auth-master
postmaster_address = postmaster@saruman.biz
mail_plugins = cmusieve
global_script_path = /data/vmail/globalsieverc
}

You could change the log path to "log_path =" With a empty logpath syslog will log the events.

Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are
driver = mysql
connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret
default_pass_scheme = PLAIN-MD5
password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u';
When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file.
chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf
chgrp vmail /etc/dovecot/dovecot.conf
chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf
/etc/init.d/dovecot restart

To get some more logging in the case something goes wrong. Uncomment the folling and change to yes.
auth_verbose = yes
auth_debug = yes
auth_debug_passwords = yes

===Dovecot SSL configuration===
Out of the (Debian) box, Dovecot is SSL-enabled. We'll now replace the generic SSL-certificate, generated for the host by the Dovecot installation script, by our own certificate. To ths end, we first [[Creating_digital_certificates_with_our_root_certificate | generate an appropriate certificate]], e.g. an SSL wildcard certificate: "*.saruman.biz". This results in a public and a private certificate, both of which must be placed somewhere where Dovecot expects them and can read them.

By default, Dovecot expects the following locations/filenames/owner/attributes:
/etc/ssl/certs/dovecot.pem -rw-r--r-- root:dovecot 4624 bytes
/etc/ssl/private/dovecot.pem -rw------- root:dovecot 1743 bytes
If we may make a suggestion: rename the generated certificates in both locations to dovecot.pem.bak, place your generated certificates in their place, and set the owner/permissions like displayed here.

However, if you've generated your own keys, you might have used a passphrase on the private key. You'll have to tell dovecot about it in its configuration file /etc/dovecot/dovecot.conf. To this end, edit the corresponding section by uncommenting the "ssl_" lines, and using your private key password (e.g. "zM7Ertq12") in the appropriate line:
ssl_cert_file = /etc/ssl/certs/dovecot.pem
ssl_key_file = /etc/ssl/private/dovecot.pem

# If key file is password protected, give the password here. Alternatively
# give it when starting dovecot with -p parameter.
ssl_key_password = zM7Ertq12
Naturally you are free to place the keys in a different location, and/or use a different name...

==Finishing up==

This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration.

===''smtpd'' TLS encryption===
The first addition we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection:
postconf -e mynetworks=
Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using
postconf -e smtpd_use_tls=yes
postconf -e smtpd_tls_auth_only=yes
Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself.

If TLS works, you'll probably want to change the certificate as you have for Dovecot in the previous section. This is again pretty easy. If you haven't yet, now is the time to [[Creating_digital_certificates_with_our_root_certificate | creating that custom SSL certificate]] for our mail server - but you have to make sure that you DON'T use a password on the private key. Unlike Dovecot, Postfix cannot be told the password to the private key somewhere.

For starters, look at the TLS-section of your ''main.cf'' that you currently have. Chances are a big chunk of it looks like this:
# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_use_tls=yes
Now all you need to do is replace the name of the snakeoil-keys with those of appropriate ssl-certificates, the private key of which needs to be NOT passphrase-protected. For this you could copy the Dovecot certificates, if you strip that passphrase in the manner described in the [[Creating_digital_certificates_with_our_root_certificate#Creating_an_SSL_certificate | SSL certificate section]]. The ''main.cf'' then would become:
# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/postfix.pem
smtpd_tls_key_file=/etc/ssl/private/postfix.key
smtpd_use_tls=yes
Restart Postfix, and presto.

=== Other additions ===
If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. One page that we want to direct you to now, is
* [[Antispam measures]] for our Postfix mailserver

Your own ownCloud

2014-01-04T09:59:26Z

Saruman!: start

Main Page

2014-01-04T09:24:19Z

Saruman!: rearrange and add ownCloud

<big>'''Welcome to SaruWiki.'''</big>

This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site].

Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software.

<big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are.

----
<big>'''Main Content'''</big>

* Setting up a [[Debian Squeeze base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet).
* Using ''md'' for [[software-based RAID]] contains our ideas and observations on redundancy.
* The use of [[APT and aptitude]] is crucial to the concept of a Debian machine.
* [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it.
* [[Essential system software]] lists all (sets of) packages that we deem, well, essential.
* The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots.
* The [[networking section]] treats subjects like setting persistent routes.
* The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling.
* The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel.
* [[Hardware monitoring]] is important for your server's health and reliability.
* Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]].
* Creating a [[backup]] for your server.

'''Authentication and security'''
* [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it.
* [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository.
* [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them

'''Your own LAMP server'''
* [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]].
* [[Database 101]] introduces you to MySQL.

'''Other server apps'''
* The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend.
* [[Add an X11 server]] to your server, if you need one.
* Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP.
* The [[Asterisk section]] is about all things re: telephony on Debian Lenny.
* [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box.
* How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now.
* How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"])
* How to create [[your own ownCloud]] server (and here's [http://www.thecomputerkid.com/2013/06/why-you-should-use-owncloud.html why] you should do this)

----
If you'd like to create a new page, please log in and go ahead
'''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team.

Database 101

2013-06-03T03:54:11Z

Saruman!: /* MySQL commands */ userdrop

== MySQL installation ==
As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Debian 5.0 "Lenny" it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. The installation script under Debian Lenny asks you for a password for the MySQL root user. Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. DO NOT use the password of the Linux ''root'' user.

Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database.

The standard user accounts that have been created by the installation script are:
* 'root'@'localhost'
* 'root'@'<hostname>'
* 'root'@'127.0.0.1'
All three root accounts are secured with the same password, the one you specified when installing the package ''mysql-server''.
----
'''NOTE for Debian 4.0 "Etch"'''
When you install MySQL under Etch, there are two root accounts with empty passwords, and two anonymous accounts. NOT safe! You'll want to rectify this in order to secure your MySQL server. Please take the following steps. Start the MySQL client from the command line:
mysql -u root
Then, from the mysql client prompt, set the password for the MySQL root users. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password:
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW');
mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW');
Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing in between them, instead of two quotes with ''root'' in between), or they can be removed - which we recommend. The (single) command for this is:
<pre>mysql> DROP USER '';</pre>
'''End of NOTE'''
----

To verify the installation you might want to take some of the following steps:
* run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql'');
* check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary);
* have a peek in ''/var/lib/mysql''; the database data files should be there;
* check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''.

==Moving the MySQL databases==
By default the location of your Debian MySQL databases is ''/var/lib/mysql/<database>''. However, sometimes you wish your databases to be in a different location. E.g. ''/data/mysql'', where ''/data'' is a mounted dedicated RAID array. Or perhaps even ''/data/mysql'' is its own array.

Whatever the reason, to move ''all'' MySQL databases from ''/var/lib/mysql'' to another location, you can follow these steps:
* Create the new directory, e.g. ''/data/mysql''
* Make this directory owned by user/group ''mysql''
cd /data
mkdir mysql
chown mysql:mysql mysql
* Shut down the database server with one of the following commands:
mysqladmin -u root -p shutdown
invoke-rc.d mysql stop
* Make a backup copy of ''/etc/mysql/my.cnf'', then edit this file. Find the section ''[mysqld]'' and change the line ''datadir = /var/lib/mysql'' to
datadir = /data/mysql
* As root, move (or better yet: copy) ''all'' of the content of ''/var/lib/mysql'' over to ''/data/mysql''. Make sure you don't accidentally change the ownership or permissions of the files and folders in the ''/var/lib/mysql'' folder. We expect each and every file and folder to be owned by ''mysql:mysql''. Copy command would be (as root):
cp -p -r /var/lib/mysql/* /data/mysql
* Check and doublecheck your ''my.cnf'' settings and your database file owners, attributes and size. After the next step, there ''may'' be no way back!
* Start up your database server:
invoke-rc.d mysql start
* Check the working of your MySQL server:
** issue the following command to get status information (to see if MySQL is running after your start command):
invoke-rc.d mysql status
** look under ''/var/log'' for the default MySQL log files ''mysql.log'' and ''mysql.err''
** check your SysLog (standard: ''/var/log/syslog'') for MySQL error messages, since the default Debian configuration is to log MySQL errors there, rather than in the previously mentioned MySQL logfiles.

== MySQL commands ==
The following are examples of the most common MySQL commands
<pre><nowiki>
SELECT User,Host from mysql.user;
SHOW GRANTS FOR '<user>'@'<host>';
GRANT <right>, <right2> ON <database>.* TO '<user>'@'<host>';
REVOKE <right>, <right2> ON <database>.* FROM '<user>'@'<host>';
DROP USER '<user>'@'<host>';
SHOW DATABASES;
USE <database>;
SHOW TABLES;
DESCRIBE <table>;
SELECT <col1>,<col2>...<col_i> FROM <table> WHERE <column> = '<value>';
INSERT INTO <table> (<col1>,<col2>...<col_i>) VALUES ('<val1>','<val2>'...'<val_i>');
UPDATE <table> set <col1> = '<value1>' WHERE <column> = '<value>';
DELETE FROM <table> WHERE <column> = '<value>';
</nowiki></pre>
Ofcourse there are more useful commands, see the MySQL website.

Talk:Main Page

2013-05-11T13:14:38Z

Saruman!: Reverted edits by 216.154.70.149 (talk) to last revision by Saruman!

You are most welcome to discuss this wiki, but please keep the discussion relevant --[[User:Saruman!|Saruman!]] 10:02, 29 March 2010 (UTC)

SaruWiki talk:Current events

2012-10-03T17:58:26Z

Saruman!: aw

hello m8 my antivirus maybe dont allow me to see all stuff in ur server ..should i login ? register?
: Heya, antivirus shouldn't block any content. Also, logging in won't allow you to see more, only to post without captcha. Maybe your browser blocks Javascript? The MediaWiki software uses some of that... By the way, there's not much more on this site than this wiki that records Linux bits'n'bobs... --[[User:Saruman!|Saruman!]] 19:58, 3 October 2012 (CEST)

Creating digital certificates with our root certificate

2012-08-16T09:33:33Z

Saruman!: /* CA.sh - certificate creation made easy */ typo's

==Preparing for certificate creation==
When we're going to create certificates, we're going to use the ''openssl'' command twice:
* once to create a "certificate signing request", in which we define all information to be included in the certificate, and actually generate the public and private key parts of the key pair, and
* once to instruct the OpenSSL package to sign the certificate with our CA root certificate.
The first step thus '''creates''' the actual keypair, and the second step '''signs''' the public key.

However, we're going to need to input a lot of parameters on the ''openssl'' command line. We can make things a bit easier for us by specifying these in the ''openssl.cnf'' file, just as we have added some values when creating the CA itself. To be precise, we're going to add '''X.509 V3 extensions'''

By default OpenSSL generates V1 certificates, but if we're not extremely worried about offending certain ancient web browsers, we can add V3 extensions, and even make ''openssl'' do that by default. To do this, we find in ''/etc/ssl/openssl.cnf'' the following line in the section ''[ req ]'', which is likely present but commented out:
req_extensions = v3_req # The extensions to add to a certificate request
Simply remove the # sign in front of it, so that it appears as given above. This by default enables V3 extensions.

Furthermore, check the section ''[ v3_req ]''. It should look like this:
[ v3_req ]

# Extensions to add to a certificate request

basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectKeyIdentifier = hash
What is added is the last line, with ''subjectKeyIdentifier''; this line specifies how to identify the public key being certified, so that distinct keys used by the same subject can be differentiated (e.g. as key updating occurs, for example). Four values are possible, but the IETF Public Key Infrastructure (PKIX) working group recommends the setting ''subjectKeyIdentifier=hash''

==Creating an SSL certificate==
Now we can create an SSL certificate for a web server. For the Common Name of the certificate, we need the '''exact''' name of the web server that'll offer the SSL connections. However, some servers run different websites as Virtual Hosts, so they could be running, for example, www.saruman.biz, as well as shop.saruman.biz. That might present a problem, because if the certificate is issued for www.saruman.biz, then each visitor of shop.saruman.biz will get a warning along the lines of "Warning: The website you're trying to visit is shop.saruman.biz, but the certificate offered is for www.saruman.biz". To prevent that, we could use the wildcard character in the name of the certificate, so as to generate a certificate for *.saruman.biz.

=== CA.sh - certificate creation made easy===
Since we have the ''openssl.cnf'' set up just right, and the ''CA.sh'' script primed, generating an SSL certificate is not very hard. From any old directory, run as root
/usr/lib/ssl/misc/CA.sh -newreq
This will create the signing request. The questions it'll ask, are
* a PEM passphrase, with which to protect the private key of the key pair. Note: you cannot generate a signing request without passphrase, so the private key you'll generate will ''always'' have a passphrase. If this is not what you want, do not despair: you can easily remove the passphrase from the private key after it's been generated (see further down). So just use a passphrase, even if you don't need one.
* Country/State/Locality/Organization/Organizational Unit; just as with the CA root certificate creation, these have your preprogrammed defaults that you may or may not change.
* Common Name; here we MUST give the DNS name of the host that is going to use the certificate, e.g. ''shop.saruman.biz'', or ''*.saruman.biz''.
* Challenge password; leave it blank, it's just to protect your signing request while en-route to the CA - but that's you anyway :-)
* Optional company name; leave that blank too, it's also extra information for the CA.

Now your private key and your certificate signing request (CSR) are ready; they're called ''newkey.pem'' and ''newreq.pem'' by default, and are located in your working directory. Time to do some signing! From that same working directory, run
/usr/lib/ssl/misc/CA.sh -sign
The script will show that it's using the config file ''/usr/lib/ssl/openssl.cnf'' (as we indeed wish), and then ask for the super-duper-secret passphrase to the CA private key (provided you've left that in directory ''/etc/ssl/ca/private''). Feed the script the passphrase, and it'll get to work. It'll check the request, then show you the details of the certificate you're about to sign. An example would be
Certificate Details:
Serial Number: 1 (0x1)
Validity
Not Before: Oct 27 09:34:00 2008 GMT
Not After : Nov 1 09:34:00 2009 GMT
Subject:
countryName = NL
stateOrProvinceName = Utrecht
organizationName = Saruman.biz
organizationalUnitName = Internet Dept.
commonName = shop.saruman.biz
emailAddress = webmaster@saruman.biz
X509v3 extensions:
X509v3 Basic Constraints:
CA:FALSE
Netscape Comment:
OpenSSL Generated Certificate
X509v3 Subject Key Identifier:
30:F2:61:80:AA:CF:1B:F0:3E:44:41:D6:38:CC:31:F0:94:28:BD:2B
X509v3 Authority Key Identifier:
keyid:80:41:F8:A5:1F:C2:27:6E:CF:A9:28:8E:8A:EF:83:E7:FD:8A:D5:26

Certificate is to be certified until Nov 1 09:34:00 2009 GMT (370 days)
Sign the certificate? [y/n]:
After doing your CA duty and diligently checking all the data, just press ''y''. The script certifies the request, and asks if it is to commit the request. This means it'll update it's own database, by saving a copy of the signed certificate in ''/etc/ssl/ca/newcerts'' named after its serial number (''01.pem'' for this example). Furthermore the script will record the serial and ID's of the generated certificate so that the next certificate will have a new serial number. And now: hey presto! We have a ''newcert.pem'' in our working directory!

For good measure:
* delete ''newreq.pem''
* rename the generated private key ''newkey.pem'' to ''shop.saruman.biz.seckey.pem''
* rename the generated public certificate ''newcert.pem'' to ''shop.saruman.biz.pem''

To remove the passphrase from the private key, use a command like this:
openssl rsa -in shop.saruman.biz.seckey.pem -out shop.saruman.biz.nokey.pem
This will make ''openssl'' ask for your passphrase, and then create the unsecured ''shop.saruman.biz.nokey.pem'' key file. Best practice: ALWAYS use a passphrase-protected key, unless the application cannot support it (e.g. Postfix).

Save the secure private key and its PEM passphrase in a safe place (e.g. Keepass database). And if you removed the passphrase from the private key, then store it in an even safer place!

Now you can deploy your certificate. (more on that in another section).

=== openssl - the hard way to certificate creation===
We don't actually need to use the ''CA.sh'' script, because we can do manually what the ''CA.sh'' script does. That gives us more control, but also more work. Let's see what we've got to do.

We will now perform the first step in our "manual" certificate generation: we create a signing request with all the information that we want in our SSL certificate. We run the magic incantation - note how we already
openssl req -new -nodes -keyout webmail.saruman.biz.key.pem -out webmail.saruman.biz.req.pem
This generates a new private key (named ''webmail.saruman.biz.key.pem''), and a new, non-encrypted (because of ''-nodes''), key signing request named ''webmail.saruman.biz.req.pem''. We can leave out terms like ''-newkey rsa:2048'' and ''-days 370'' since we've put that in the configuration file. And naturally you're free to choose your own names for the keys.

FIXME - need the full process here

=== Validating the generated certificates===
Again, we can use the ''openssl'' command to validate the keys we've generated. For instance, the ''CA.sh'' generated certificate, after renaming, is verified with
openssl x509 -in shop.saruman.biz.pem -noout -purpose
Certificate purposes:
SSL client : Yes
SSL client CA : No
SSL server : Yes
SSL server CA : No
Netscape SSL server : Yes
Netscape SSL server CA : No
S/MIME signing : Yes
S/MIME signing CA : No
S/MIME encryption : Yes
S/MIME encryption CA : No
CRL signing : Yes
CRL signing CA : No
Any Purpose : Yes
Any Purpose CA : Yes
OCSP helper : Yes
OCSP helper CA : No
Notice that the certificate is valid for everything except CA tasks.

Likewise, using ''-dates'' instead of ''-purpose'' lets you see the validity time period, and ''-text'' gives the whole text of the certificate. Note the line marked "issuer", and see how your own CA is referenced there.

DLNA server

2012-08-05T17:46:02Z

Saruman!:

Target of this section of the wiki is to explain how to install and configure your Debian server so that it can act as a multimedia repository for your DLNA-capable equipment. In this case, we're going to optimize our DLNA server for a Samsung SmartTV, which supports Samsung's "AllShare", a slightly extended variant of DLNA.
==Compiling and installing==
We start out by downloading the latest version of MiniDLNA from its [http://sourceforge.net/projects/minidlna/files/ SourceForge website]. At the time of writing, it's version 1.0.25. This file is extracted to the '''/usr/src/''' directory:
localhost:/usr/src# '''tar xzf minidlna_1.0.25_src.tar.gz'''
localhost:/usr/src# '''cd minidlna-1.0.25/'''
localhost:/usr/srcminidlna-1.0.25# '''make'''
./genconfig.sh

ERROR! Cannot continue.
The following required libraries are either missing, or are missing development headers:

libavcodec libavformat libavutil libflac libvorbis libogg libid3tag libexif libjpeg

make: *** [config.h] Error 1
localhost:/usr/srcminidlna-1.0.25# '''_'''
MiniDLNA has some dependencies; executing the ''make'' command has shown us which dependencies are unfulfilled (your list will probably differ). In the above case, the cure for the missing libraries is
''localhost:/usr/src# '''apt-get install libavcodec-dev libavformat-dev libflac-dev libvorbis-dev libexif-dev libjpeg-dev libid3tag0-dev''' ''
After installing all packages that MiniDLNA needs, the output of ''make'' may be similar to:
localhost:/usr/src/minidlna-1.0.25# '''make'''
./genconfig.sh
Compiling minidlna.c
Compiling upnphttp.c
Compiling upnpdescgen.c
Compiling upnpsoap.c
Compiling upnpreplyparse.c
Compiling minixml.c
Compiling getifaddr.c
Compiling daemonize.c
Compiling upnpglobalvars.c
Compiling options.c
Compiling minissdp.c
Compiling uuid.c
Compiling upnpevents.c
Compiling sql.c
Compiling utils.c
Compiling metadata.c
Compiling scanner.c
scanner.c: In function âinsert_containersâ:
scanner.c:172: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:195: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:207: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:276: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:281: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:297: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:318: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:323: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:338: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
Compiling inotify.c
Compiling tivo_utils.c
Compiling tivo_beacon.c
Compiling tivo_commands.c
Compiling tagutils/textutils.c
Compiling tagutils/misc.c
Compiling tagutils/tagutils.c
Compiling playlist.c
Compiling image_utils.c
Compiling albumart.c
Compiling log.c
Linking minidlna
Compiling testupnpdescgen.c
Linking testupnpdescgen
localhost:/usr/src/minidlna-1.0.25# '''_'''
After succesful compilation, we can simply install with
localhost:/usr/src/minidlna-1.0.25# '''make install'''
install -d /usr/sbin
install minidlna /usr/sbin
localhost:/usr/src/minidlna-1.0.25# '''_'''
==Starting MiniDLNA==

DLNA server

2012-08-05T15:54:14Z

Saruman!:

Target of this section of the wiki is to explain how to install and configure your Debian server so that it can act as a multimedia repository for your DLNA-capable equipment. In this case, we're going to optimize our DLNA server for a Samsung SmartTV, which supports Samsung's "AllShare", a slightly extended variant of DLNA.

We start out by downloading the latest version of MiniDLNA from its [http://sourceforge.net/projects/minidlna/files/ SourceForge website]. At the time of writing, it's version 1.0.25. This file is extracted to the '''/usr/src/''' directory:
localhost:/usr/src# '''tar xzf minidlna_1.0.25_src.tar.gz'''
localhost:/usr/src# '''cd minidlna-1.0.25/'''
localhost:/usr/srcminidlna-1.0.25# '''make'''
./genconfig.sh

ERROR! Cannot continue.
The following required libraries are either missing, or are missing development headers:

libavcodec libavformat libavutil libflac libvorbis libogg libid3tag libexif libjpeg

make: *** [config.h] Error 1
localhost:/usr/srcminidlna-1.0.25# '''_'''
MiniDLNA has some dependencies; executing the ''make'' command has shown us which dependencies are unfulfilled (your list will probably differ). In the above case, the cure for the missing libraries is
''localhost:/usr/src# '''apt-get install libavcodec-dev libavformat-dev libflac-dev libvorbis-dev libexif-dev libjpeg-dev libid3tag0-dev''' ''
After installing all packages that MiniDLNA needs, the output of ''make'' may be similar to:
localhost:/usr/src/minidlna-1.0.25# '''make'''
./genconfig.sh
Compiling minidlna.c
Compiling upnphttp.c
Compiling upnpdescgen.c
Compiling upnpsoap.c
Compiling upnpreplyparse.c
Compiling minixml.c
Compiling getifaddr.c
Compiling daemonize.c
Compiling upnpglobalvars.c
Compiling options.c
Compiling minissdp.c
Compiling uuid.c
Compiling upnpevents.c
Compiling sql.c
Compiling utils.c
Compiling metadata.c
Compiling scanner.c
scanner.c: In function âinsert_containersâ:
scanner.c:172: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:195: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:207: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:276: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:281: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:297: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:318: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:323: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:338: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
Compiling inotify.c
Compiling tivo_utils.c
Compiling tivo_beacon.c
Compiling tivo_commands.c
Compiling tagutils/textutils.c
Compiling tagutils/misc.c
Compiling tagutils/tagutils.c
Compiling playlist.c
Compiling image_utils.c
Compiling albumart.c
Compiling log.c
Linking minidlna
Compiling testupnpdescgen.c
Linking testupnpdescgen
localhost:/usr/src/minidlna-1.0.25# '''_'''

DLNA server

2012-08-05T15:51:05Z

Saruman!:

Target of this section of the wiki is to explain how to install and configure your Debian server so that it can act as a multimedia repository for your DLNA-capable equipment. In this case, we're going to optimize our DLNA server for a Samsung SmartTV, which supports Samsung's "AllShare", a slightly extended variant of DLNA.

We start out by downloading the latest version of MiniDLNA from its [http://sourceforge.net/projects/minidlna/files/ SourceForge website]. At the time of writing, it's version 1.0.25. This file is extracted to the '''/usr/src/''' directory:
'''localhost:/usr/src# ''tar xzf minidlna_1.0.25_src.tar.gz''
localhost:/usr/src# ''cd minidlna-1.0.25/''
localhost:/usr/srcminidlna-1.0.25# ''make''
./genconfig.sh

ERROR! Cannot continue.
The following required libraries are either missing, or are missing development headers:

libavcodec libavformat libavutil libflac libvorbis libogg libid3tag libexif libjpeg

make: *** [config.h] Error 1
localhost:/usr/srcminidlna-1.0.25# ''_'''''
MiniDLNA has some dependencies; executing the '''make''' command has shown us which dependencies are unfulfilled (your list will probably differ). In the above case, the cure for the missing libraries is
'''localhost:/usr/src# ''apt-get install libavcodec-dev libavformat-dev libflac-dev libvorbis-dev libexif-dev libjpeg-dev libid3tag0-dev'''''
After installing all packages that MiniDLNA needs, the output of '''make''' becomes:
'''dworkin:/usr/src/minidlna-1.0.25# ''make''
./genconfig.sh
Compiling minidlna.c
Compiling upnphttp.c
Compiling upnpdescgen.c
Compiling upnpsoap.c
Compiling upnpreplyparse.c
Compiling minixml.c
Compiling getifaddr.c
Compiling daemonize.c
Compiling upnpglobalvars.c
Compiling options.c
Compiling minissdp.c
Compiling uuid.c
Compiling upnpevents.c
Compiling sql.c
Compiling utils.c
Compiling metadata.c
Compiling scanner.c
scanner.c: In function âinsert_containersâ:
scanner.c:172: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:195: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:207: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:276: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:281: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:297: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:318: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â
scanner.c:323: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
scanner.c:338: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â
Compiling inotify.c
Compiling tivo_utils.c
Compiling tivo_beacon.c
Compiling tivo_commands.c
Compiling tagutils/textutils.c
Compiling tagutils/misc.c
Compiling tagutils/tagutils.c
Compiling playlist.c
Compiling image_utils.c
Compiling albumart.c
Compiling log.c
Linking minidlna
Compiling testupnpdescgen.c
Linking testupnpdescgen
dworkin:/usr/src/minidlna-1.0.25# ''_'''''

APT and aptitude

2012-08-05T15:30:05Z

Saruman!: added apt-file

==Using APT and Aptitude==

Your Debian system can easily be expanded, and also kept up-to-date with the latest security fixes, if you use Debian's beautiful [http://www.debian.org/doc/manuals/apt-howto/ch1.en.html APT (Advanced Packaging Technology)] tools. Of all available [http://en.wikipedia.org/wiki/Advanced_Packaging_Tool APT-based tools], we usually use the following:
* apt-get, the command line utilities that go with APT; or
* aptitude, a [http://en.wikipedia.org/wiki/Curses_%28programming_library%29 curses-based] frontend for APT.

These APT-based tools are incredibly powerful and flexible, but we're not going to explain them fully here (for tuturials and whatnot, go [http://www.debian.org/doc/manuals/apt-howto/ here]). What we need to establish now, is how to configure APT, and how to use it.

APT gets its information from a configuration file that can be found in ''/etc/apt''. Of these, the most important is ''sources.list'' because it defines what packages and updates can be installed from where, and even what version of Debian we want to maintain. For now let's just suffice to say that in the sources.list, you need to remove the references to the CD-ROm with which you installed the system, and specify which on-line repository you wish to use for installing and updating packages. To this end, open ''/etc/apt/sources.list'' with [[Vim | your favourite text editor]] while you are logged in as root.

References to the CD-ROM look a bit like this:
deb cdrom:[Debian GNU/Linux testing _Etch_ - Official Beta i386 CD Binary-1 20070317-21:45]/ etch contrib main
Disable this line by putting a hash (#) in front of it (you could have more than one line beginning with ''deb cdrom:'').

Now make sure you have a section that references one or more on-line repositories. This could make your ''sources.list'' look like this:
<pre>
# deb cdrom:[Debian GNU/Linux testing _Etch_ - Official Beta i386 CD Binary-1 20070317-21:45]/ etch contrib main

deb ftp://ftp.nl.debian.org/debian/ etch main contrib
deb-src ftp://ftp.nl.debian.org/debian/ etch main contrib

deb http://security.debian.org/ etch/updates main contrib
deb-src http://security.debian.org/ etch/updates main contrib

# deb ftp://ftp.nl.debian.org/debian-volatile etch/volatile main contrib

</pre>

When you want to update, change, add software, or even remove software, you better update your APT system by running one of the following commands:
* sudo apt-get update
* sudo aptitude update
* sudo aptitude, then press ''u''
Note: if you haven't installed [[sudo]] yet, then you can only run the commands as root, and they are then: ''apt-get update'', ''aptitude update'', and ''aptitude'' then ''u''.

==Getting informed on installed packages==
You might at some time wonder if a package is already installed. Usually, you'd check this using
dpkg --get-selections
The output of this can be rather unwieldy, but you can send the output to a program like ''grep'' to refine your search. As an example: use
dpkg --get-selections | grep install -c
to see just how many packages you have.

But this standard command doesn't directly concerns itself with versions or installation history.

Now if you're wondering what version a specific package (or set of packages) is, then you can install package ''apt-show-versions'' and run it on the command line; if you wish to know the version of a particular file, e.g. ''sudo'', you'd run
apt-show-versions sudo
This package is described on [http://www.debianadmin.com/list-your-installed-package-versions-with-apt-show-versions.html Debian Admin]. It can do much more, but there's a fine ''man'' page for that.

Furthermore, if you're interested in the installation history of your packages, you could check out the ''dpkg'' log file, by default ''/var/log/dpkg.log''. This logging file/location is set in ''/etc/dpkg/dpkg.cfg''. So to find the installation time/date of all programs, you could execute
grep "status installed" /var/log/dpkg.log

==Getting information on packages that are NOT installed==
This can be done with a package named '''apt-file'''. More information [http://www.debianhelp.co.uk/findfile.htm here].

DLNA server

2012-08-05T15:19:01Z

Saruman!: start

Main Page

2012-08-05T15:11:31Z

Saruman!: dlna

<big>'''Welcome to SaruWiki.'''</big>

This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site].

Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software.

<big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are.

----
<big>'''Main Content'''</big>

* Setting up a [[Debian Squeeze base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet).
* Using ''md'' for [[software-based RAID]] contains our ideas and observations on redundancy.
* The use of [[APT and aptitude]] is crucial to the concept of a Debian machine.
* [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it.
* [[Essential system software]] lists all (sets of) packages that we deem, well, essential.
* [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]].
* [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them
* [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it.
* [[Database 101]] introduces you to MySQL.
* [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository.
* The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend.
* [[Add an X11 server]] to your server, if you need one.
* Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP.
* The [[Asterisk section]] is about all things re: telephony on Debian Lenny.
* The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots.
* The [[networking section]] treats subjects like setting persistent routes.
* The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling.
* The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel.
* [[Hardware monitoring]] is important for your server's health and reliability.
* [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box.
* Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]].
* Creating a [[backup]] for your server.
* How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now.
* How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"])
If you'd like to create a new page, please log in and go ahead:
<inputbox>
type=create
</inputbox>
----
'''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team.
----
<websiteFrame>
website=http://www.google.com/talk/service/badge/Show?tk=z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&w=200&h=60
border=0
height=60
width=200
name=GoogleChatwithSaruman!
allowtransparency=true
</websiteFrame>

Talk:IPsec tunneling diagnostics

2012-07-11T18:05:37Z

Saruman!:

Here's a specific tip for diagnosing ipsec tunnel difficulties. If nothing is happening -- the tunnel doesn't seem to be activating, and there isn't any output about it at all -- it's probable that your security policy configuration is incorrect, so nothing is even trying to use the tunnel. In my case, I got the direction of the traffic mixed up, and tried to say "inbound traffic from myself to machine XYZ should go through the tunnel" (and vice versa). Since I was just working with IP addresses, it was really easy to get them backwards and not notice that fact without a rigorous inspection. Once I reversed the direction and was able to get some output in my logs, my other issues were much easier to identify. :)

Here's my other specific tip. Output like "ERROR: phase1 negotiation failed due to time up." may mean "check your firewalls, you're probably blocking the port. and then when you're done, check your OTHER firewall." (If you're on Amazon EC2, that means to check your security groups, including (if you're in a VPC) both inbound and outbound rules, and subnet ACLs.

-- [[Special:Contributions/174.62.124.8|174.62.124.8]] 23:48, 8 July 2012 (CEST)
: Good tips! Thanks, --[[User:Saruman!|Saruman!]] 20:05, 11 July 2012 (CEST)

APT and aptitude

2012-05-27T08:35:23Z

Saruman!: added inform.