Authelia is an open-source authentication and authorization server. In conjunction with an NGINX proxy, all pf your proxied apps and services can use the the same login credentials and login session - that is sign in once and have access to all you services without signing in again. It also offers 2FA via email, Google Authenticator, Duo, and Yubikey.

Scenario

This guide outlines setting up Authelia in the following scenario:

• On a webserver running Ubuntu 18.04s.
• NGINX is used to proxy a number of apps and services.
• Authelia will be run in a docker container.
• Authelia will be deployed in the "light" deployment.

Prerequisites

This guide assumes you have done or know how to do the following:

• You have created a DNS entry for the subdomain auth.example.com pointing to your server.
• Your apps and services are proxied to either your root domain or some subdomains.
• You are familiar with adding SSL certificates to NGINX (If not, check out Let's Encrypt).

Authelia Configuration & Installation

1. The first step is to install the docker, docker-compose and git packages to prepare for the installation of Authelia.

   We want to install Docker from the official Docker repository to ensure we get the latest version. The following set of commands prepares the repository.

   sudo apt update
   sudo apt install apt-transport-https ca-certificates \
       curl software-properties-common
   curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
       | sudo apt-key add -
   sudo add-apt-repository "deb [arch=amd64] \
       https://download.docker.com/linux/ubuntu \
       $(lsb_release -cs) stable"
   sudo apt-get update
   

   Now to actually install the packages:

   sudo apt-get install docker-ce docker-ce-cli docker-compose git
   

   All that's left to do is add your user to the docker group so you can manage docker without having to use sudo all the time:

   sudo usermod -aG docker ${USER}
   su - ${USER}
   

2. Now we'll begin installing Authelia. First we'll create a directory to contain all of Authelia's configuration files and any dependencies. In my case it will be in my users home directory.

   mkdir ~/authelia
   cd ~/authelia
   

3. To get started were going to make a docker-compose.yml to define the docker containers we're creating. Create a file named docker-compose.yml in your editor of choice and paste the following:

   version: '3.3'
    
   networks:
     net:
       driver: bridge
   
   services:
     authelia:
       image: authelia/authelia
       container_name: authelia
       volumes:
         - ./authelia:/config
       networks:
         - net
       ports:
         - 9091:9091
       restart: unless-stopped
       environment:
         - PUID=1000
         - PGID=1000
         - TZ=America/Vancouver
   
     redis:
       image: redis:alpine
       container_name: redis_authelia
       volumes:
         - ./redis:/data
       networks:
         - net
       expose:
         - 6379
       restart: unless-stopped
       environment:
         - TZ=America/Vancouver
         - PUID=1000
         - PGID=1000
   

   Now we'll work through the contents of this file and I'll point out the changes you'll need to make depending on your setup.

   The first several lines just specify the oldest version of docker engine this file will work with, and the type of network driver docker should use. You probably won't need to change anything here.

   Under services you will find Authelia itself. As well as redis, a database system Authelia uses. As-is in the file each service will have
   their respective files in subdirectories of the directory docker-compose.yml is is. If you prefer some other setup, those can be changed.

   Change PUID and GUID on lines 19, 20, 35, and 36 to your users id's (find your own id's with id $user).

   Change America\Vancouver on lines 21 and 34 to your local timezone (find a list of timezones known to you system with timedatectl list-timezones).

4. Now we'll make the first of Authelia's configuration files.

   mkdir ~/authelia/authelia
   cd ~/authelia/authelia
   

   Create and open configuration.yml in your editor of choice and paste the following:

   server:
     host: 0.0.0.0
     port: 9091
   log:
     level: info
   jwt_secret: <your-secret-key>
   default_redirection_url: https://apps.example.com
    
   authentication_backend:
     file:
       path: /config/users_database.yml
    
   access_control:
     default_policy: deny
     rules:
       - domain:
           - "auth.example.com"
         policy: bypass
       - domain:
           - "example.com"
           - "*.example.com"
           - "app.example.com"
         policy: one_factor
    
   session:
     name: authelia_session
     secret: <your-secret-key>
     expiration: 12h           # 12 hours
     inactivity: 45m           # 45 minutes
     remember_me_duration: 1M  # 1 month
     domain: example.com
    
     redis:
       host: redis_authelia
       port: 6379
    
   regulation:
     max_retries: 3
     find_time: 5m
     ban_time: 15m
    
   storage:
     encryption_key: <your-encryption-key>
     local:
       path: /config/db.sqlite3
    
   notifier:
     #filesystem:
       #filename: /config/notification.txt
     smtp:
       username: test@gmail.com
       password: <gmail_password>
       host: smtp.gmail.com
       port: 587
       sender: test@gmail.com
   

   The first thing to replace in configuration.yml is <your-secret-key> after jwt_secret on line 6, secret on line 27, and <your-encryption-key> on line 43. You should replace these with unique strings. If you want, the command below can be used to generate random seeds. Just make usre to use unique strings for each of the three screts.

   head /dev/urandom | tr -dc A-Za-z0-9 | head -c64
   

   The rest of the options you'll likely want to change are:

   • default_redirection_url: The URL users who navigate directly to the login page will be redirected to after login.
   • access_control: This is the area of the configuration where you set what kind of authentication is required for different subdomains. Rules are defined as a list of domains and the policy they follow.
     • In the configuration template the default_policy is deny and there are two domain rules:
       • The first is a bypass rule allowing anyone to the auth page and the root of the domain. Change these to match your domain.
     • policy: There are four policy options:
       • deny - No access is permitted.
       • one_factor - Login with username and password.
       • two_factor - Login with username, password, and 2FA.
       • bypass - No login required.
     • For more details on the access control list, see the docs.
   • session: This is where cookie setting are set.
     • expiration: How long before the cookie expires.
     • inactivity: Mow much inactivity will cause the cookie to expire.
     • remember_me_duration: How long you will stay signed in for after ticking "remember me".
   • regulation: If there are max_retries failed login attempts in find_time, you will be banned for ban_time.
   • notifier: This is how 2FA codes will be delivered. The template config is setup for emails to be sent from a Gmail address. You can fill this out with your Gmail information, or some other email services smtp settings. Alternatively, comment out all the email settings and uncomment the filesystem ones. This way 2FA codes will just be saved to the listed file.

   For more information or additional configuration options, you can refer to the docs or the sample config.

5. The last bit of configuration is creating the user data base. In the same directory as the configuration.yml file, create a new file called users_database.yml and put the following into it.

   users:
     <username>:
       displayname: "Your Name"
       # Generate with docker run authelia/authelia:latest authelia hash-password <your-password>
       password: "<hashed-password>"
       email: <your-email>
       groups:
         - admins
   

   Replace <username> with your desired username, Your Name with your full name and <your-email> with your email. To get the hashed-password to replace <hashed-password> with, use the following command.

   docker run authelia/authelia:latest authelia hash-password <your-password>
   

   You can add as many users as you like under the users: key. You can also add yourself or any other users to more groups if you want to do access control based on groups.

6. We are now ready to spin up Authelia. cd back to the directory containing docker-compose.yml and run the following command to create and run the containers.

   docker-compose up -d
   

   If everything went smoothly, you should be able to navigate to <webserver-ip>:9091 and be presented with Authelia's login prompt. Try the username and password you setup in step 5!

Adding Authelia to NGINX

Now that Authelia is setup and running, it's time to tie it into NGINX.

7. The first thing we need to do is create a new site configuration for auth.example.com. For example:

   sudo vim /etc/sudo vim /etc/nginx/sites-available/auth.example.com
   

   Of course, replace example.com with your domain name. Paste the following into the new configuration file:

   server {
       server_name auth.example.com;
       listen 80;
       return 301 https://$server_name$request_uri;
   }
   
   server {
       server_name auth.example.com;
       listen 443 ssl http2;
   
       location / {
           set $upstream_authelia http://127.0.0.1:9091;
           proxy_pass $upstream_authelia;
   
           client_body_buffer_size 128k;
   
           #Timeout if the real server is dead
           proxy_next_upstream error timeout invalid_header http_500 http_502     http_503;
   
           # Advanced Proxy Config
           send_timeout 5m;
           proxy_read_timeout 360;
           proxy_send_timeout 360;
           proxy_connect_timeout 360;
   
           # Basic Proxy Config
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
           proxy_set_header X-Forwarded-Host $http_host;
           proxy_set_header X-Forwarded-Uri $request_uri;
           proxy_set_header X-Forwarded-Ssl on;
           proxy_redirect  http://  $scheme://;
           proxy_http_version 1.1;
           proxy_set_header Connection "";
           proxy_cache_bypass $cookie_session;
           proxy_no_cache $cookie_session;
           proxy_buffers 64 256k;
   
           # If behind reverse proxy, forwards the correct IP
           set_real_ip_from 10.0.0.0/8;
           set_real_ip_from 172.0.0.0/8;
           set_real_ip_from 192.168.0.0/16;
           set_real_ip_from fc00::/7;
           real_ip_header X-Forwarded-For;
           real_ip_recursive on;
       }
   }
   

   Replace all occurrences of example.com with your domain name. Then to enable this new site, run:

   sudo ln -s /etc/nginx/sites-available/auth.example.com /etc/nginx/sites-enabled/auth.example.com
   sudo systemctl reload nginx
   

   Now is a good time to get an SSL certificate for auth.example.com. An example of how to do this with letsencrypt's certbot:

   sudo certbot run -d auth.example.com --nginx
   

   Now try navigating to auth.example.com. If all went well, you should again see the Authelia login prompt.

8. Now we'll make a couple configuration snippets to make adding Authelia to our sites easier. Create and open a file /etc/nginx/snippets/authelia.conf and the past the following into it.

   # Virtual endpoint created by nginx to forward auth requests.
   location /authelia {
       internal;
       set $upstream_authelia http://127.0.0.1:9091/api/verify;
       proxy_pass_request_body off;
       proxy_pass $upstream_authelia;    
       proxy_set_header Content-Length "";
   
       # Timeout if the real server is dead
       proxy_next_upstream error timeout invalid_header http_500 http_502 http_503;
   
       # [REQUIRED] Needed by Authelia to check authorizations of the resource.
       # Provide either X-Original-URL and X-Forwarded-Proto or
       # X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Uri or both.
       # Those headers will be used by Authelia to deduce the target url of the     user.
       # Basic Proxy Config
       client_body_buffer_size 128k;
       proxy_set_header Host $host;
       proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $remote_addr; 
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Forwarded-Host $http_host;
       proxy_set_header X-Forwarded-Uri $request_uri;
       proxy_set_header X-Forwarded-Ssl on;
       proxy_redirect  http://  $scheme://;
       proxy_http_version 1.1;
       proxy_set_header Connection "";
       proxy_cache_bypass $cookie_session;
       proxy_no_cache $cookie_session;
       proxy_buffers 4 32k;
   
       # Advanced Proxy Config
       send_timeout 5m;
       proxy_read_timeout 240;
       proxy_send_timeout 240;
       proxy_connect_timeout 240;
   }
   

   This snippet will be added to the server block of any site we secure with Authelia. We need one more snippet. Create and open /etc/nginx/snippets/auth.conf, then paste the following in.

   # Basic Authelia Config
   # Send a subsequent request to Authelia to verify if the user is authenticated
   # and has the right permissions to access the resource.
   auth_request /authelia;
   # Set the `target_url` variable based on the request. It will be used to build the portal
   # URL with the correct redirection parameter.
   auth_request_set $target_url $scheme://$http_host$request_uri;
   # Set the X-Forwarded-User and X-Forwarded-Groups with the headers
   # returned by Authelia for the backends which can consume them.
   # This is not safe, as the backend must make sure that they come from the
   # proxy. In the future, it's gonna be safe to just use OAuth.
   auth_request_set $user $upstream_http_remote_user;
   auth_request_set $groups $upstream_http_remote_groups;
   auth_request_set $name $upstream_http_remote_name;
   auth_request_set $email $upstream_http_remote_email;
   proxy_set_header Remote-User $user;
   proxy_set_header Remote-Groups $groups;
   proxy_set_header Remote-Name $name;
   proxy_set_header Remote-Email $email;
   # If Authelia returns 401, then nginx redirects the user to the login portal.
   # If it returns 200, then the request pass through to the backend.
   # For other type of errors, nginx will handle them as usual.
   error_page 401 =302 https://auth.example.com/?rd=$target_url;
   

   All you need to do here is replace example.com on the last line with your domain.

9. Now we can edit our existing example.com NGINX site config to add Authelia.

   • You will include the snippet authelia.conf into the main server block.
   • You will include the snippet auth.conf into any location block you want to protect.

   For example:

   server {
       server_name app.example.com;
       listen 80;
       return 301 https://$server_name$request_uri;
   }
   
   server {
       server_name app.example.com;
       listen 443 ssl http2;
       include snippet/ssl.conf;
   
       include snippets/authelia.conf; # Authelia auth endpoint
   
       location / {
           proxy_pass http://proxied:service;
   	    proxy_set_header Host $host;
   	    proxy_set_header X-Real-IP $remote_addr;
   	    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   
   	    include snippets/auth.conf; # Protect this endpoint
       }
   }
   

   You should just be able to add the snippets in the correct locations to your existing configuration.

   Test the configuration and then reload NGINX:

   sudo nginx -t
   sudo systemctl reload nginx
   

   Congratulations! If everything your done!

Test It Out

Try navigating to any protected endpoint you configured, you should be presented with the login prompt. After entering your credentials, you should be redirected to your destination. If you setup multiple endpoints, going to a second one should not ask for a password because you are still logged in.

If you want to logout, you can navigate to auth.example.com and you will be presented with a logout button. auth.example.com/logout will also accomplish the same.

Down the line: Updating

Because we used docker-compose to bring up this system updating any part of it is very simple. Just run the following commands to pull the latest images and then rebuild and start the containers.

cd ~/authelia
docker-compose pull
docker-compose up --force-recreate --build -d
docker image prune -f

Resources

• You can download all the configuration templates here.
• See the official Authelia docs here.
• Have a look at the official, complete sample config here.

Email me with any suggestions or feedback!

If you only have access to a public Wi-Fi network while working with your Raspberry Pi, or the only Wi-Fi network available to you is 5 GHz, you may want to share the internet connection from your Windows laptop or computer with your Pi over ethernet. You can use Window's Internet Connection Sharing (ICS) feature to help you do this. Below are the steps required to set it up so it reliably works across reboots.

Steps

1. Open Windows Control Panel and navigate to Control Panel> Network and Internet > Network and Sharing Center. Click Change Adapter Settings in the left-hand panel and you should be presented with a list of network adapters:
   
2. Identify the Wi-Fi adapter with the active internet connection that you would like to share, and the Ethernet adapter you would like to share the connection to. In my case, the Wi-Fi adapter is called Wi-Fi and the ethernet adapter is called Ethernet.
3. Right-click on the Wi-Fi adapter, and select Properties, then select the Sharing tab in the top of the window.
   
4. Tick the "Allow other users to connect through..." box and then select the ethernet adapter identified in step 2 from the drop-down menu below. Click ok.
   You should now see Shared beside the name of the Wi-Fi network you are connected to on the Wi-Fi adapter item.
5. To make the ICS service startup automatically with Windows, search for Services in the start menu and open the Windows services utility.
   
6. Find the service called Internet Connection Services (ICS), right-click it and select Properties. Select Automatic from the Startup type drop-down menu. Then click OK and exit the services utility.
   
7. To make the ICS service actually work after a reboot we need to create a registry key. Search for and open the Registry Editor in the start menu. Paste Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedAccess into the adress bar at the top of the window. Right-click anywhere and select New > DWORD (32-bit) Value. Name the new key EnableRebootPersistConnection. Double click the new key and change the Value data field to 1.
   

At this point you should be all set. Plug your Raspberry Pi into the ethernet port of your computer, and power it up. You should see the ethernet activity lights on the Pi blinking away as Windows assigns it a new IP from the 192.168.137.* sub-net. Because Windows will assign your Pi an IP, you wont know what IP to use to ssh into it. You can test the connection as well as resolve the IP by opening a command prompt window in typing ping raspberrypi.mshome.net where rasperrypi is the hostname of the Pi (raspberrypi is the default).

If all is well, you will see a response from the resolved IP of the Pi. To ssh into the Pi, you can either enter raspberrypi.mshome.net or the resolved IP into PuTTY, but be aware that the IP will likely change every time you connect the Pi.

Troubleshooting

• If you can ping the Pi but can't connect via ssh, ensure that ssh is enabled. See the Raspberry Pi documentation for details on this.
• If you can connect to the Pi but it cant reach the outside internet, make sure your computer is connected to the internet via Wi-Fi.
• If the ICS stops working after a reboot, and you are sure steps 5-7 were done properly, you may be forced to disable and re-enable ICS in the Wi-Fi adapter settings after every reboot. This is a known issue with Windows some people have encountered.

Often when working with microcontrollers, it is necessary to interface with buttons of many kinds. One thing that needs to be considered is no switch or button switches from one state to another perfectly cleanly. Because of this, the microcontroller could see multiple 'button presses' when only one occurred. To handle this, we must do something called debouncing.

On the image shown below, you can see the output of an active-high button in yellow, and the clean output signal of the micro in blue. Looking to the start of the yellow trace, it initially goes high but for approximately 2ms, its state is unstable. The blue trace shows the output of the micro, going high when it decides that button has stabilized.

My preferred  debounce strategy is based on an algorithm I have found through Kenneth Kuhn, debounce.c found here. His files outlines a strategy in which the state of the button is read on a regular interval. On each read, depending on the state, an 'integrator' value is either added to or subtracted from by one. If that value reaches a fixed threshold, then output goes high. It only goes low once the value returns to 0.

Below is my implementation of this algorithm in a simple function. By calling poll_btn(0) on a timer (I usually put in in a timer interrupt that triggers every millisecond or so), at any point in you code you can check if poll_btn(1) returns a 1.

#define BTNPORT PINB
#define BTNPIN 3

#define DEBOUNCECYCLES 5

uint8_t poll_btn(uint8_t number) {
	static uint8_t integrator;
	static uint8_t output;

	switch(number) {
		case 0 :
			// Poll and integrate fire and set buttons
			if ((BTNPORT & (1<<BTNPIN))) {
				if (integrator > 0) {
					integrator--;
				}
			} else if (integrator < DEBOUNCECYCLES) {
				integrator++;
			}
			return(0);

		case 1 :
			// If integrator is at threshhold, return 1
			// If integrator is at 0, return 0
			if (integrator == 0) {
				output = 0;
			}
			else if (integrator >= DEBOUNCECYCLES) {
				integrator = DEBOUNCECYCLES;
				output = 1;
			}
			return(output);
	}
	return(0);
}

The function could be easily expanded to more inputs by adding their polling and integrating code to case 0 and making a new case to check them.

Email me with any suggestions or questions!

Recently while browsing Digikey, I came across a new-to-me AVR microcontroller, the ATtiny1616 (Datasheet here). It has impressive specs and an extremely reasonable price (less than $1.50CAD in single quantities). But, there are a few caveats to contend with. It is only available in SMD packages which can make prototyping a little bit tricky, and bigger than that, it doesn't use the classic AVRISP programmer.

This micro came out after the Atmel-Microchip merger and is part of the new tinyAVR 1-Series. This means that it has a few key differences to AVR's that you may be familiar with. The most significant to the actual process of developing with it is your AVRISP programmer is unable to program it. It uses a new programming interface called UPDI which stands for Unified Program and Debug Interface. The lowest-cost official programmer for it seems to be the Atmel-ICE which costs over $150. Fortunatley there is a cheaper, easier solution that you probably have the parts for - pyupdi.

pyupdi is a is a driver written in python that lets you turn a simple usb to serial adapter into a UPDI programmer using a single resistor. To set it up, all you need to do is connect the RX pin of the adapter to the UPDI pin on the micro and the TX pin to that through a 4.7k resistor. Then just use the program on your computer.

The other thing you may have to deal with if you choose to use these new microcontrollers are the SMD packages. Fortunately, SOIC packages are relativley easy to hand-solder and breakout boards can be had for cheap on Digikey or anywhere else.

As a simple hello-world project to get used to the new device, I chose to use some seven segment displays I recently got. I wanted to try multiplexing and this was the perfect opportunity. I built up the following circuit and then got to programming.

The seven segment displays are common-cathode to each of the commons is connected to an I/O pin on the micro. Then each of the segment pins are connected to each display ans well as seven more I/Os. Ideally, each segment pin would get a resistor instead of resistors on the common cathode but i just wanted to keep the wring clean so I opted for this setup. Because of this, the brightness depends on how many segments are turned on.

The code is relatively simple, just increasing the number displayed. It can be found below:

#define  F_CPU 3300000
#include <avr/io.h>
#include <util/delay.h>

int main(void)
{
	PORTB.DIR = 0xFF;
	PORTA.DIR = 0xFF;
	PORTA.OUT = 0x00;

	char SegA[] = {0x80, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x80, 0x00, 0x00, 0x00, 0x00, 0x80, 0x00, 0x00, 0x00};
	char SegB[] = {0xC0, 0xF9, 0xE4, 0xF0, 0xD9, 0xD2, 0xC2, 0xF8, 0xC0, 0xD8, 0xC8, 0xC3, 0xC6, 0xE1, 0xC6, 0xCE};

	int count = 0;

	int DispA = 0;
	int DispB = 0;
	int DispC = 0;
	int DispD = 0;

    while (1) {
		count ++;

		PORTA.OUT = (PORTA.OUT & ~0b10000000) | (SegA[DispA] & 0b10000000);
		PORTB.OUT = (PORTB.OUT & ~0b00111111) | (SegB[DispA] & 0b00111111);
		PORTA.OUT |= (1 << 1);
		_delay_us(30);
		PORTA.OUT &= ~(1 << 1);

		PORTA.OUT = (PORTA.OUT & ~0b10000000) | (SegA[DispB] & 0b10000000);
		PORTB.OUT = (PORTB.OUT & ~0b00111111) | (SegB[DispB] & 0b00111111);
		PORTA.OUT |= (1 << 2);
		_delay_us(30);
		PORTA.OUT &= ~(1 << 2);

		PORTA.OUT = (PORTA.OUT & ~0b10000000) | (SegA[DispC] & 0b10000000);
		PORTB.OUT = (PORTB.OUT & ~0b00111111) | (SegB[DispC] & 0b00111111);
		PORTA.OUT |= (1 << 3);
		_delay_us(30);
		PORTA.OUT &= ~(1 << 3);

		PORTA.OUT = (PORTA.OUT & ~0b10000000) | (SegA[DispD] & 0b10000000);
		PORTB.OUT = (PORTB.OUT & ~0b00111111) | (SegB[DispD] & 0b00111111);
		PORTA.OUT |= (1 << 4);
		_delay_us(30);
		PORTA.OUT &= ~(1 << 4);


		if (count >= 25) {
			count = 0;
			DispD++;
			if (DispD > 9) {
				DispC++;
				DispD = 0;
				if (DispC > 9) {
					DispB++;
					DispC = 0;
					DispD = 0;
					if (DispB > 9) {
						DispA++;
						DispB = 0;
						DispC = 0;
						DispD = 0;
						if (DispA > 9) {
							DispA = 0;
							DispB = 0;
							DispC = 0;
							DispD = 0;
						}
					}
				}
			}
		}
	}
}

If you are using Atmel studio, you can set the custom programming command to this, changing the path and COM port to however your system is set up. path\to\python.exe path\to\pyupdi.py -d tiny1616 -c COM# -f $(OutputDirectory)$(OutputFileName).hex This way pressing Start Without Debugging will build and upload your program. More details here.

To program from the command line, use the command python path\to\pyupdi.py -d tiny1616 -c COMX -f yourfile.hex -v. If everything is hooked up correctly, you should be all set!

Troubleshooting

If you are having some issues, try going through the following:

• Ensure the ground of the adapter is connected to the ground of your circuit.
• Make sure you have all python dependencies installed (pip install intelhex pylint pyserial).
• The voltage of your serial adapter should be the same as your circuit.
• Nothing else can be using the COM port.
• Python 3 should work but some people have had issues. Try 2.7.
• Make sure you don't disable the UPDI pin with fuses. You'll need a high-voltage programmer (Big $$$) to recover your chip.
• If you are on Linux, your COM port will likely be /dev/tty<something>. Make sure your user is the group for tty access (usually uucp), and test out your serial connection before trying pyupdi. If all is well both with your software and hardware (4.7K resistor), any characters you send should be echoed right back.

Helpful Links

• mraardvark's pyupdi [github]
• ATtiny1616 datasheet [microchip]
• USB Serial adapter I used [amazon]

Email me with any suggestions or questions!

NGINX vs Apache, while they both have their pros and cons, one stands out clearly for self hosting - NGINX. There are a few key reasons for this including the following:

• Lightweight - When self hosting, you have limited resources. NGINX uses fewer resources.
• Reverse Proxy - Many of your services are going to run on weird ports without encryption. NGINX allows you to access them from convenient URLs using HTTPS encryption.
• Easy Configuration - You don't need to be an expert to understand NGINX config files.
• It just works.

This guide will go over installing NGINX, basic configuration, enabling PHP, setting up server blocks, getting and using free SSL, setting up reverse proxy, and using the alias function.

Installation

Installation is easy, just use your distributions package manager to install the NGINX package:

Ubuntu/Debian:

apt-get install nginx

You can find instructions for other distributions here.

Once installed, just head over to your server IP or domain in a web browser and you should see the following page:

If so then you're good to start configuring!

Basic Configuration

The default config file or 'server block' is located at /etc/nginx/sites-available/default. If you stripped out all the comments, then it would look like this:

server {
listen 80 default_server;
listen [::]:80 default_server;

root /var/www/html;
index index.html index.htm index.nginx-debian.html;

server_name _;

location / {
try_files $uri $uri/ =404;
}
}

At first it may seem as though there is a lot going on. Here's a rundown of everything:

• The listen lines tell the server what port to run on. 80 is the standard for HTTP, 443 for HTTPS. The default_server string means all requests will go here is there is no other block for them. It can only be in 1 server block.
• Root tells the server where on the server the files you want to serve are.
• index tells the server what file should be served when you just go to the IP or URL.
• server name tells the server what domain to listen for. _ is any.
• The location block just says that if the request can't be served, return a 404.

Before we begin making changes, we want to make a backup of the default block. This is so if something gets really messed up, we can restore it easily. We'll also install PHP now so we can enable it in the config.

cp /etc/nginx/sites-available/default /etc/nginx/sites-available/default.old

Enabling PHP

PHP is an extremely common server side scripting language. Unlike Apache, NGINX does not integrate PHP natively. Instead, whenever it needs to serve some PHP, it makes a call to an external PHP server process. While this tends to make the configuration slightly more complex, it cuts down on overhead and improves performance.

First you need to install the php-fpm package:

apt-get install php-fpm

Now one quick security improvement we can make is edit the php.ini file. It is usually located at /etc/php/7.0/fpm/php.ini. You want to find the commented out line called cgi.fix_pathinfo, make sure it is uncommented and set to 0. Great! Now we can tell NGINX to use PHP-FPM to process PHP files.

Open up the default server block in your text editor of choice and add this location block to the bottom of the server { } block. While your at it, update the index command by adding index.php.

location ~ .php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php7.0-fpm.sock;
}

Now make a new file called info.php in your web root and add <? phpinfo(); ?> to it. Now if you head over to http://yourdomain/info.php, you should see somthing similar to the following:

Cool, Now your all set with PHP!

Server Blocks (Virtual Hosts)

You'll likely want to run multiple domains or subdomains serving different services through the same server. If you need your own domain, I can personally recommend NameCheap. With NGINX, this is easy. First, we need to copy the default server block for our new domain. Name the copy whatever your domain is to keep things organized, make a new web root, and then open the new config to edit:

cd /etc/nginx/sites-available
cp /etc/nginx/sites-available/default /etc/nginx/sites-available/my.domain.com
mkdir -R /var/www/mydomain/html

Now for what to change.

1. Remove default_server from the first 2 listen lines.
2. Change the root to the new directory you made.
3. Replace the _ by server_name to your domain. For example, my.domain.com.

That's it; now to enable the server block we need to link it to the enabled directory, test it and then reload the web server:

ln -s my.domain.com ../sites-enabled/my.domain.com
nginx -t
service nginx reload

Now head over to the domain you should get a 404. If you do that great, that means that instead of going through the default config and showing the NGINX welcome, it looking in the web root you set and found nothing. Now you can add whatever content you want to the new folder you made; just make sure it's owner and group is the user that is running web server process (eg. www-data).

You can repeat this process for however many domains you want to use. Just remember to remove default_server and change the root to something new.

Let's Encrypt SSL Certificates

SSL encryption is an important part of any public web services. They encrypt all data sent to and from the server to prevent man-in-the-middle attacks. And, now that you can get free, signed SSL certs through Lets Encrypt, there's no reason not to.

Setting Up

First, we need to get the letsencrypt and openssl package. On Ubuntu, sudo apt-get install letsencrypt openssl does the job. Then we need to make a small change to all server blocks we want to secure. Add the following line to each server block:

location ~ /.well-known {
allow all;
}

Then just reload with service nginx reload. Now generate a strong DH group with the following command: sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048. This might take a few minutes so sit tight. Great, now were set to make get some certs.

Getting Certificates

To get your certificates, your going to run the next command but you'll have to change a few things. Set --webroot-path= to whatever your root is, set -d to your domain.

sudo letsencrypt certonly --webroot --webroot-path=/var/www/html -d example.com

If successful, it should print out where your certificates were placed. Niw we can go install the certs.

Installing Certificates

Now we need to make a few snippets to add to our server block. Change all example.com your domain.

#/etc/nginx/snippets/ssl-example.com.conf

ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

#/etc/nginx/snippets/ssl-params.com.conf

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_prefer_server_ciphers on;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_ecdh_curve secp384r1;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;

ssl_dhparam /etc/ssl/certs/dhparam.pem;

Great now that we've got the snippets, we can apply them to the server block. Make your server block look like the following with your own info and snippets:

server {
listen 80;
listen [::]:80;
server_name example.com;
return 301 https://$server_name$request_uri;
}

server {
# SSL configuration

listen 443 ssl http2;
listen [::]:443 ssl http2;
include snippets/ssl-example.com.conf;
include snippets/ssl-params.conf;

root /var/www/example/html;

index index.html index.php index.htm index.nginx-debian.html;

server_name example.com;

location / {
try_files $uri $uri/ /index.php?$args;
}

location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php7.0-fpm.sock;
}

location ~ /\.ht {
deny all;
}

location ~ /.well-known {
allow all;
}

}

Now reload NGINX. Now if you head over to your domain it shout redirect to the HTTPS version and you should see a green lock! Perfect!

Reverse Proxy

When self hosting, its very common to end up with lots of services running on a number of ports. You can make it much easier to access and share all the these services using a reverse proxy. As an example I'll proxy Sonarr, a popular self hosted media app from the default of ip:8989 to example.com/sonarr. Since I already have a server block setup with SSL for example.com, this will be super simple.

It's just a matter of opening up the server block and adding a location block. Then change the directory of the location block to whatever you want it to be. Lastly replace the IP and port to that of your Sonarr install.

location /sonarr {
proxy_pass http://192.168.1.12:8989;
proxy_set_header Host $host; #DO NOT CHANGE
proxy_set_header X-Real-IP $remote_addr; #DO NOT CHANGE
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; #DO NOT CHANGE
}

Then you just need to go to Sonarrs settings and set the base url as sonarr and reload bot Sonarr and NGINX. Now if you head over to example.com/sonarr you'll see your sonarr, just without that pesky port.

Alias

If you want to run an app like WordPress, at a URI like example.com/blog but you want all files related to it to be in a different directory, you'd use the alias function. One quirk is you need to add your PHP for PHP to work. Check this out:

location /alternative {
alias /var/www/alternative_html/;
location ~ /\.php$ {
fastcgi_pass unix:/run/php/php7.0-fpm.sock;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $request_filename;
}
}

You can change alternative and alternative_html to whatever you like then you should be all set.

Now that you've got a secure, robust and lightweight web server, you can install Koel - a self hosted music server. Or not. It's really up to you :)

Last Updated: 07/11/17

Unfortunately, if you've done some searching, you may have found out that Atmel's IDE, Atmel Studio is windows only. There is no official Atmel Studio linux. The best alternative I have found is the Eclipse IDE with the AVR plugin.

Note: While this guide is written for Linux, you can use it on windows or Mac OSX of you don't like Atmel studio or want to try something new.

Installation

Dependencies

Before we install eclipse and the AVR plugin, we need a few packages. Install avrdude, avr-gcc, avr-libc, avr-binutils, and avr-gdb.

Eclipse

First you wnat to install the excellent Eclipse C/C++ IDE. Depending on what operating system you are on the process will be different. For most linux distorbutions, you need to install the eclipse-cpp package.

Once installed, you want to open it up and create a new workspace for your AVR projects. Now open the Eclipse Marketplace Help > Eclipse Marketplace. Search for and install the AVR Eclipse Plugin.

Usage

Creating a new project

To make a new project, select File > New > C Project', choose a name and then pick AVR Cross Target Application` from the dialog box and press next. Press next again and then select your projects chip and frequency. These can be changed later in the project properties. Then press finish.

Writing your code

To begin creating source code for your program, close the Welcome tab and in the left Project Explorer panel, right click and select New > File; Name it main.c. Now you can code away.

Building your project

To build your project, first right click you project in the explorer and pick Build Configurations > Set Active > 2 Releasemake sure all files are saved and press Project > Build all or just Ctrl-B. You should see the build progress in the console at the bottom of the screen. For Directions on setting up a programmer with eclipse and programming your micro controller, got here.

There you go, You should be all set up with an equivalent Atmel Studio Linux! Now you can code away to your hearts content on the operating system of your choosing!