This page contains everything you need to get started using freelan quickly. However, you might face a situation where you are stuck or where something doesn't work like you would expect. In this situation, you may want to get help from humans.

The official way to get help, is to write to the users mailing-list at users@freelan.org. Registering is easy and straighforward, as well as unregistering.

You may also choose to ask your question on Super User, by tagging it freelan. If you do so, please make sure you first read the FAQ and that your question is on-topic before you ask anything. Keep in mind that Super User is not the official FreeLAN support channel and that you may get no answer.

While you do so, please be accurate in the description of your problem. Namely, please give us:

• Your operating system, including its architecture (32 bits, 64 bits).
• The specific version of freelan you installed (giving the download link is appreciated).
• The network environment you are trying to setup freelan in.
• The configuration files for your different nodes.
• The log output of freelan that contains the error, if any.

Keep in mind that the more accurate and complete you are in your question, the higher the chances are that someone will answer it quickly.

If some information is missing in your question, the answer will likely ask you to give the configuration file or the log output anyway, so please take the time to write your question right from the start.

If you want, you can also register to the users mailing-list by sending an empty email to users-subscribe@freelan.org. This allows you to help other users in turn by receiving their questions. Registering to the users mailing-list is really appreciated by the developers.

Signaling bugs

If you spotted a bug in freelan, or want to make a feature request, you may file a Github issue.

If you don't have a Github account, you can also write to the developers mailing-list at dev@freelan.org to submit your feature request or your bug.

Please do not write to the developers mailing-list to ask configuration questions. This mailing-list is dedicated to freelan's development, not user assistance. You will get better chances by writing to the users mailing-list instead.

Configuration

This section explains the most important options in freelan's configuration file. To get complete configuration samples go to this page.

• A quick note on certificates
• The tools
• Creating the CA
• Client certificate generation
• Adjusting the configuration

---

A quick note on certificates

Freelan relies on X509 certificates for its security. Certificates work in pair with private keys to provide both authenticity and confidentiality.

Certificate generation is sometimes considered as a difficult task, due to the complexity of the tools that are involved. We believe it is important to understand the base principle before generating certificates.

Certificates are files that contains information about an entity (usually an Internet host, in this case your computer). Namely, they contain:

• The hostname to which this certificate is associated.
• The relevant country, company, email address information.
• A validity period (start date and stop date) for the certificate.
• A public RSA key.
• A reference to the Certification Authority (CA) that signed the certificate.

The certificate comes in pair with a private key that matches the public key embedded in the certificate. You may give the public key (or the certificate) to anyone. It is not a secret and must be considered public the moment you generate it.

On the other hand, the private key is private, and must never, ever, be published anywhere. Ideally, private keys are best kept on an encrypted disk, offline whenever possible. The important point being: nobody except you needs your private key. So don't give it to anyone.

While you can of course use an official certificate authority to sign your certificates for use with freelan, you may also decide to create your own private CA for personal use.

The rest of this starter guide will assume the following:

• You want a custom CA to sign all your certificates for use with freelan.
• Your CA will sign all the client certificates of all your freelan hosts.
• You will publish your CA certificate and your client certificates to all the hosts.

So let's get started !

---

The tools

We will use the command line to generate our certificates. First download and install openssl and make sure it is in your PATH.

---

Creating the CA

Get the certificate authority sample folder archive and extract it where you like.

Go inside the extracted folder and type:

openssl req -new -x509 -extensions v3_ca -keyout key/ca.key -out crt/ca.crt -config ca.cnf

When prompted for a passphrase, type what you want, but remember it ! You will have to type it whenever the certificate authority private key file will be needed.

You should now have a certificate file at crt/ca.crt and its associated private key file at key/ca.key.

---

Client certificate generation

Now that you have a working certificate authority, it is time to generate client certificates. Repeat the following step for every certificate/private key pair you need.

Private key generation

The first step is to generate a private key:

openssl genrsa -out alice.key 4096

If you wish to protect your private key with a passphrase, use the following command line instead:

openssl genrsa -des3 -out alice.key 4096

Note: Using a passphrase will increase the security of your private key. Even if it gets stolen, the password will be required to use the private key. However, setting a passphrase on the private key can prevent its use in automated systems.

This will generate a file named alice.key. This is the client private key.

Note: every host should generate its own private key to keep it secret. The certificate authority does not need the client private key to sign the client certificate.

Issuing a certificate request

Now that a client has a private key, it must generate a certificate request out of it. This certificate request will be "send" to the certificate authority which can then chose to accept it and generate a signed certificate from it.

To generate a certificate request, type the following command:

openssl req -new -sha1 -key alice.key -out alice.csr

Fill all the certificate request attributes.

This will generate a file named alice.csr. This is the client certificate request.

Note: Those two steps (private key and certificate request generation) do NOT need to be done in the certificate authority folder. Actually, they should even be done on the final host directly for privacy's sake.

Generating a signed certificate from a certificate request

The final step is to generated a signed certificate from the certificate request. This is obviously done on the CA.

Type the following command:

openssl ca -out crt/alice.crt -in alice.csr -config ca.cnf

This will prompt for the ca.key passphrase then ask you whether you want to accept the certificate request.

This will generate a alice.crt file: the client signed certificate which can be send to anyone.

Repeat these steps for every client, and you will have everything you need to use freelan ! Congratulations !

---

Adjusting the configuration

The default freelan's configuration is incomplete: more precisely, the entries about the certificates to use are left blank. Let's fill those in to get freelan working !

Open the configuration file (see configuration instructions in the download page for details about where to find the configuration for your operating system) and locate the following lines:

# The X509 certificate file to use for signing.
#
# Unless server.enabled is set to "yes", this parameter is mandatory.
#
# Default: <none>
#signature_certificate_file=

# The private key file to use for signing.
#
# Unless server.enabled is set to "yes", this parameter is mandatory.
#
# This private key must match with the specified signing certificate file.
#
# Default: <none>
#signature_private_key_file=

Uncomment the two configuration lines and specify the path to your certificate and private key. Here is an example:

# The X509 certificate file to use for signing.
#
# Unless server.enabled is set to "yes", this parameter is mandatory.
#
# Default: <none>
signature_certificate_file=/etc/freelan/mycert.crt

# The private key file to use for signing.
#
# Unless server.enabled is set to "yes", this parameter is mandatory.
#
# This private key must match with the specified signing certificate file.
#
# Default: <none>
signature_private_key_file=/etc/freelan/mykey.key

Now locate the following lines:

# The authority certificates.
#
# You may repeat the authority_certificate_file option to specify several
# authority certificates.
#
# Default: <none>
#authority_certificate_file=

And uncomment the configuration line to indicate to freelan the path to your CA certificate. Here is an example:

# The authority certificates.
#
# You may repeat the authority_certificate_file option to specify several
# authority certificates.
#
# Default: <none>
authority_certificate_file=/etc/freelan/ca.crt

To specify your IP address on the network, locate the following lines:

# The tap adapter IPv4 address and prefix length to use.
#
# The network address must be in numeric format with a netmask suffix.
#
# On Windows, the prefix length is ignored (but still must be specified) and
# the netmask is determined according to the IPv4 class. It is recommended that
# you set the network.enable_dhcp_proxy option.
#
# You may specify an empty value.
#
# Default: 9.0.0.1/24
ipv4_address_prefix_length=9.0.0.1/24

Replace 9.0.0.1 with the IP address you would like this host to have.

Finally, indicate to freelan where to contact the other hosts by locating these lines:

# The contact list.
#
# The list of hosts to connect to.
#
# You may repeat the contact option to add several hosts.
#
# Examples: 192.168.0.1, [fe80::1]:12000, hostname:1234, some.other.host.org:1234
# Default: <none>
#contact=192.168.0.1:12000

Uncomment and repeat the contact= line for all the different hosts you want to contact. Here is an example:

# The contact list.
#
# The list of hosts to connect to.
#
# You may repeat the contact option to add several hosts.
#
# Examples: 192.168.0.1, [fe80::1]:12000, hostname:1234, some.other.host.org:1234
# Default: <none>
contact=192.168.0.1:12000
contact=[fe80::1]:12000
contact=myhost.dyndns.org:15000

Freelan will attempt to periodically contact those hosts to establish a connection.

---

Go back to the downloads.