DEV Community: Joshua Rothe

Self-Hosting a Vaultwarden Password Manager

Joshua Rothe — Fri, 27 Mar 2026 19:29:16 +0000

Full text can also be viewed here.

Password vaults are a convenient and secure way to manage multiple passwords. As data breaches become more and more common, security guidance changes lead to an inevitable mishmash of credentials that are impossible to remember when not used daily. The logic behind constantly-evolving password guidelines is beyond the scope of this guide, but recent word from NIST on password vaults recommends their use:

Verifiers SHALL allow the use of password managers and autofill functionality. Verifiers SHOULD permit claimants to use the “paste” function when entering a password to facilitate password manager use when password autofill APIs are unavailable. Password managers have been shown to increase the likelihood that subscribers will choose stronger passwords, particularly if the password managers include password generators

This guide walks through setting up a lightweight, locally-hosted password manager that allows the user (or users) to keep their accesses secure without needing to perform superhuman feats of memorization. It is written assuming the reader has a fully configured WireGuard VPN server on their home network, with all local traffic handled by the VPN specifically. This is necessary for security, not just for Vaultwarden; it's generally much simpler and safer to stand up your devops infrastructure when you don't have to open ports to the entire internet.

Background

A password vault (or password manager) is a secure, encrypted digital storage system for username and password combinations. Remembering one password is much simpler than having to remember multiple. Why NIST took so long to come to this conclusion is out of scope for this guide, but feel free to enjoy others' discourse on the topic.

Source: xkcd 936

There are several password managers to choose from; Bitwarden is a strong contender in the space, and I highly recommend it for the average person or enterprise. It is open source, has weathered security audits, and you can even self-host it. With their cloud-hosted service, your data is encrypted locally before it's sent to their servers, so even Bitwarden themselves could not access your information.

Some downsides exist, though; it's a resource hog when hosted locally, and resources matter when you keep stacking services on your home Debian device. The average user does not need the scalability and infrastructure that it provides. Additionally, some services such as autofilling passwords require a paid subscription, even when self-hosting.

Thus, this guide settles on Vaultwarden for a self-hosted password vault. Vaultwarden is a lightweight re-write of Bitwarden in Rust; it uses much less CPU and RAM (~50MB to Bitwarden's ~1-2GB), and as a bonus it is easier to set up. The process is explained below; the length of this write-up should speak to its simplicity.

Prerequisites

WireGuard VPN, configured to handle local address traffic.
Linux server (Debian, can be the same machine hosting the WireGuard VPN).
Basic command line familiarity.

Initial Setup

On the server meant to host the Vaultwarden instance, you will need to install podman and set up the necessary folder structure in your home directory. You will also need to set up a self-signing certificate (acceptable since we are on a VPN). Note that docker is also an option and most guides reference it; I prefer podman since it is more secure by not requiring root access and not having a single point of failure (dockerd).

First, find your server's IP address. You will need to replace 192.168.1.100 below with your server's IP address. With the correct IP, run the following to execute the podman install, folder structure creation, and certificate generation:

sudo apt update && sudo apt upgrade -y
sudo apt install podman podman-compose git -y
mkdir -p ~/vaultwarden/{data,config,ssl}
cd ~/vaultwarden
echo "ADMIN_TOKEN=$(openssl rand -hex 32)" > .env
chmod 600 .env
openssl req -x509 -newkey rsa:4096 -keyout ssl/private.key -out ssl/certificate.crt -days 36500 -nodes -subj "/CN=192.168.1.100"
chmod 600 ssl/private.key
chmod 644 ssl/certificate.crt

The certificate expires in 100 years (36,500 days). Expiration cannot be disabled completely, but if you have it set for a year your password manager may break and you could waste hours debugging the self-signed certificate you've since forgotten about.

You may also need to open the HTTPS port on your firewall if you use UFW. Run sudo ufw status and if it shows as active, run:

sudo ufw allow from 192.168.1.0/24 to any port 8443

Configuration

Still within the ~/vaultwarden folder, create docker-compose.yml by running the following (again, replace 192.168.1.100 with the correct IP address):

cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  vaultwarden:
    image: docker.io/vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    env_file:
      - .env
    environment:
      WEBSOCKET_ENABLED: 'true'
      SIGNUPS_ALLOWED: 'true'
      DOMAIN: 'https://192.168.1.100:8443'
      ROCKET_TLS: '{certs="/ssl/certificate.crt",key="/ssl/private.key"}'
      LOG_LEVEL: 'warn'
      EXTENDED_LOGGING: 'true'
    volumes:
      - ./data:/data
      - ./ssl:/ssl:ro
    ports:
      - "8443:80"
      - "3012:3012"
EOF

Now run the container and check status:

podman-compose up -d
podman ps

You should see the docker.io/vaultwarden/server:latest container running.

Account Setup

Access the admin console by typing https://192.168.1.100:8443 (replace the IP address) into a browser. You will be prompted to create the username and password, and then download the Bitwarden password manager addon. It works perfectly with Vaultwarden and autofills your passwords, so this is highly recommended.

Next, configure it for your self-hosted server when logging in by selecting 'self-hosted' at login rather than 'bitwarden.com'. Use the admin console URL/port again, and log in using the login created earlier.

Automated Start/Restart of Server

The last step here is to ensure Vaultwarden starts back up if the server reboots or has a power failure. This is also very simple to set up by running the following:

systemctl --user enable podman.service
sudo loginctl enable-linger $USER

podman generate systemd --new --name vaultwarden --files
mkdir -p ~/.config/systemd/user
mv container-vaultwarden.service ~/.config/systemd/user/

podman-compose down
systemctl --user daemon-reload
systemctl --user enable container-vaultwarden.service
systemctl --user start container-vaultwarden.service

systemctl --user status container-vaultwarden.service
podman ps

The above code sets up auto-start configuration and generates a systemd file for the Vaultwarden service, then brings the Vaultwarden container down to switch over from podman-compose management to systemd management. The last two lines check status; if these look good, you are done.

Conclusion

You should now be able to use Vaultwarden in the browser of your choice. It should (when logged in) prompt you with the option to save passwords, and autopopulate them as needed. I hope this was helpful; if you notice any issues with this guide or process, please feel free to reach out or leave a comment.

Xilinx/AMD Vivado SoC FPGA Development and Debug Workflow

Joshua Rothe — Sat, 18 Oct 2025 22:51:47 +0000

Cover image source: AMD/Xilinx Zynq-7000 SoC Data Sheet: Overview DS190 (v1.11.1) July 2, 2018, Figure 1

Full text can also be viewed here.

Verification of an FPGA design post-synthesis involves several steps, which can be incrementally worked through as the design matures. The following guide provides a decent outline to carry a design from post-simulation all the way to implementation alongside a SoC processor that can control and read the FPGA from software. I originally wrote this guide while working on my Master's degree, and revised it into a checklist as I found myself doing the same workflows. In situations where one missed step could require you to endlessly debug a phantom issue, it is helpful to have a repeatable process. While this guide is not all-encompassing, it functions as an excellent base framework for a junior FPGA designer to work from.

FPGA Overview (Written for Non-FPGA Developers)

FPGAs are programmable hardware devices that are made up of a grid of repeating programmable logic blocks called "slices" and various other interlinked components, which have rapidly increased in complexity and performance in recent years. A modern Zynq Ultrascale+ MPSoC has two processors (APU and RPU), a GPU, various on-chip memory types (RAM, block RAM, distributed RAM), DMA controllers, serial transceivers, and dedicated I/O interfaces. On the boards they are mounted on, you will also often see additional memory types (DDR3/4), ADC and DACs, I/O peripherals, and more.

Slices vary based on hardware but usually have the same general types of components. Referred to as Configurable Logic Blocks (CLBs) on the Ultrascale MPSoC, they are made up of Look-Up Tables (LUTs), flip-flops (FFs), and multiplexers. Some have additional components like adders or other logic gates thrown in.

Newer FPGAs also have DSP slices, which are dedicated logic blocks for adders, multipliers, accumulators etc. and are instantiated differently to free up the CLBs (or, to reverse that, to free up the valuable multipliers and adders).

When an FPGA is programmed, code such as SystemVerilog (syntactically similar to C) directs the synthesizer to connect or disconnect these slices, filling the lookup tables appropriately to achieve the coded performance on hardware. Understanding how the code synthesizes onto the FPGA is very important for the designer to know for several reasons.

Since you are programming hardware, some code is not synthesizable as it makes no sense to the compiler to put it on hardware. Examples include "wait" statements, or the "real" datatype. It is also important to be mindful that everything happens in parallel on hardware unless otherwise specified (e.g. a clock is added), so race conditions must be avoided and typical hardware design concerns such as set up time and hold time must be considered (this is referred to as timing closure in FPGA design, and is beyond the scope of this guide).
You will want your code to utilize the resources on the FPGA as well as hardware resources on the board, and will need to design appropriately for your device. Instead of creating a large array of registers (which will not always properly synthesize into BRAM), you generally will want to instantiate a Xilinx IP for the BRAM component on the board in order to utilize it reliably. Clock signals, rather than being generated with regular FPGA fabric logic (e.g. counters or clock dividers), should be generated from dedicated clocking primitives (PLLs, MMCMs) to avoid poor timing and other issues.
The processor(s), if used, need to be instantiated and connected to the design. How the design will be controlled from software must be considered, and those components must also be linked and created.
How hardware components such as DDR3/4, DACs/ADCs, and I/O peripherals need to be controlled properly, which may include both firmware instantiation of controllers as well as proper register manipulation from software.
Building off of the previous two items, the component.xml file is hardware specific and must define the coded signals to the correct chip pins. Some proprietary FPGA synthesizers have a pre-configured setup, which also needs to be understood by the designer since that generally cannot be changed.

For Xilinx FPGA design, the options are High Level Synthesis (HLS) coding in Vitis or Register Transfer Level (RTL) code in Vivado. RTL is typically preferred by electrical and FPGA engineers who need more control over hardware resources and timing, whereas HLS appeals more to software and embedded developers who can leverage C/C++ familiarity for rapid prototyping. This guide focuses on Vivado and RTL specifically, though Vitis is used in the debugging process as well.

The following sections provide a step-by-step workflow for project creation through hardware debugging, assuming the reader has RTL source files ready for implementation.

Building a Project

Manually create a project in Xilinx Vivado with no sources, selecting only the applicable part type. Source files are then added to the project, and sim files are added separately (as they will be considered sim-only and not for synthesis). This project build can later be automated with .tcl scripts, including the creation of a block diagram, once these source files are added and (if applicable) a block diagram is created. The actual construction of these source files is beyond the scope of this guide, but it assumes .sv, .v, or .vhd files.

It is recommended to keep the source files linked, so that as they are modified the source files outside of the project will continuously update and can be re-added when a project is rebuilt. This may not always be desired behavior, however; especially if you have an automated .tcl build workflow that manages source file versions independently.

Typically, Vivado projects themselves are not saved, as rebuilding Vivado projects is a common way to fix many errors. The project files should be added to .gitignore in most cases.

Timing Constraints and Synthesis/Implementation Analysis

Before proceeding to hardware debugging, proper timing constraints need to be defined in the constraints .xdc file. All clocks should be defined by create_clock entries, and set_clock_groups should define all clock domain crossings. Input or output delays relative to external devices should also be defined using set_input_delay and set_output_delay, respectively. An example is shown below, which can be added to the top-level project's constraints file.

# Primary clock constraints.
create_clock -period 10.000 -name sys_clk_100mhz [get_ports sys_clk]
create_clock -period 20.000 -name ext_clk_50mhz [get_ports ext_clk]

# Zynq processor clocks are auto-constrained when using Zynq IP, but any clocks generated from custom PLLs need manual definition.
create_generated_clock -name custom_clk_200mhz -source [get_ports sys_clk] -multiply_by 2 [get_pins custom_pll_inst/clk_out]

# Clock domain crossings - mark asynchronous clock groups which do not have a phase relationship.
set_clock_groups -asynchronous -group [get_clocks sys_clk_100mhz] -group [get_clocks ext_clk_50mhz]
set_clock_groups -asynchronous -group [get_clocks sys_clk_100mhz] -group [get_clocks custom_clk_200mhz]

# Input delays for external devices (ADC example with 2ns setup, 1ns hold).
set_input_delay -clock [get_clocks sys_clk_100mhz] -max 2.0 [get_ports {adc_data[*]}]
set_input_delay -clock [get_clocks sys_clk_100mhz] -min 1.0 [get_ports {adc_data[*]}]

# Output delays for external devices (DAC example with 3ns setup, 1ns hold).
set_output_delay -clock [get_clocks sys_clk_100mhz] -max 3.0 [get_ports {dac_data[*]}]
set_output_delay -clock [get_clocks sys_clk_100mhz] -min 1.0 [get_ports {dac_data[*]}]

# False paths for reset signals (asynchronous resets don't need timing analysis). Also used if proper clock domain crossing circuits are being used - basically, avoids timing analysis.
set_false_path -from [get_ports sys_reset_n]

# Multicycle paths (if there is logic that takes multiple clock cycles, e.g. pipelining or time-multiplexing expensive operations).
set_multicycle_path -setup 2 -from [get_pins slow_logic_reg*/C] -to [get_pins output_reg*/D]
set_multicycle_path -hold 1 -from [get_pins slow_logic_reg*/C] -to [get_pins output_reg*/D]

Above definitions will be required for Vivado to provide an accurate timing analysis.

After implementation, review the following:

Timing Summary: All timing constraints should be met. No negative slack. Failure to meet timing requires redesign, possibly adding latches between long datapaths (beyond the scope of this guide).
Utilization Report: Aim for at most 80%, though many designers typically shoot for 60%-70%. You can run report_qor_assessment to get exact thresholds (defined by Xilinx/AMD) for utilization targets; staying below these values gives the best QoR (quality of results) and easier timing closure. As utilization approaches 100%, the place and route tools have to work much harder to meet timing; this can also result in longer build times.
Power Consumption: Verify it is within board capabilities. The system that you are integrating into likely has additional restrictions for power utilization that will need to be followed.

Debugging Workflow over JTAG

This instruction is intended for reference when revising an IP that exists (or will exist) within a larger block diagram. This allows for debugging using the XSCT console in Vitis as well as the Vivado ILA (Integrated Logic Analyzer). Overall goal is to verify functionality of an FPGA build by reading/manipulating registers and viewing the waveform outputs prior to adding the complexity of an OS (and related software code) to the design. This instruction assumes a Zynq processor or similar is on the chip, and there is/will be a software layer of some sort on that processor, which applies to most modern FPGAs. This instruction also assumes all of the simulation work has been completed, which is beyond the scope of this guide.

IP Creation

In Vivado, design and simulate the RTL code for the IP. Once this is satisfactory, select Implementation > Run Implementation from the Flow Navigator (left panel in Vivado GUI).

Once implementation is complete, go to Tools > Package New IP. Click through the prompts.

Select Packaging Options > Package your current project on the second page.
On the third page, choose an IP location that your overall block diagram project can pull from (here, src/ip/), and create a sub-folder specifically for this IP, named appropriately. Select this folder as the location. If rebuilding an existing IP, it is important to overwrite the same folder so that the block diagram automatically updates.
Once the Package IP tab comes up, take care of any issues. The Addressing and Memory tab will allow for registers to be mapped out (select the proper size for the register in question if needed, so it is not taking up too much address space). After this, the File Groups tab allows you to merge changes from the wizard. Finally, go to the Review and Package tab and select Re-package IP. The temporary IP project will close.

Block Diagram Implementation

Please note that block diagrams can also be implemented within a top-level RTL. The constraints will need to be set up accordingly for whichever the top level design is.

For first-time implementation only:

Go to the IP Catalog in the Flow Navigator and right-click the background of the primary window. Select Add Repository and add the location of the custom IP to the project. Then select Open Block Design and add the IP to the block diagram. Connect as necessary in the Diagram tab, and ensure the addressing is set up properly for any registers in the Address Editor tab.

Debug Core Setup:

(Note: This section is written specifically for SoC processor integration.)

Right click connections in the diagram that you would like debug probes to be added to, and select Debug. This can be done to entire AXI/AXIS connections, or simple I/Os.
Add a Zynq processor IP block to the design. Double-click the Zynq processor block to configure, and navigate to the PS-PL Configuration. Within the PS-PL Cross Trigger interface, enable Input Cross Trigger > Cross Trigger Input 0 > CPU0 DBG REQ and Output Cross Trigger > Cross Trigger Output 0 > CPU0 DBG ACK.
Select Run Connection Automation for the block diagram. It will connect the triggers to the Zynq processor, as well as the debug connections, to the ILA block that is automatically added. Double-click to configure the ILA block as needed. This also needs to be done if any new debug cores are added.
Now go to Flow Navigator > Open Synthesized Design and select Set Up Debug. Add the corresponding nets that were added previously. *This also needs to be done if any new debug cores were added.
Finally, Generate Bitstream, and this should save the bitstream in the project's projectname.runs/impl_1/ folder.

For subsequent implementations:

Vivado will detect the IP was upgraded and will prompt you to go to Report IP Status, then Upgrade the IP. Edits to the block diagram and ILA nets may be needed for some changes (reference the above italics).

Connecting to Hardware and Programming

If the target is local, you can simply Connect to the Local Target. This applies only when the FPGA board is connected directly to the computer running Vivado via a JTAG cable (note: newer Xilinx development boards have built-in JTAG functionality and this cable is now simply a USB-type cable).

Most likely, the target is connected to a remote server. For Xilinx Vitis/Vivado debug purposes, it will need to be connected via the JTAG cable or interface.

Follow these instructions to connect to a remote hardware server:

First, ssh into the server that the FPGA board is connected to via a USB-to-JTAG connection. Ensure the board's switches are configured to allow for JTAG programming (which varies by board). So the connection stays awake even without user input, run the following command to ssh into the server (with appropriate username and IP):

ssh -X -o ServerAliveInterval=30 username@SERVER.IP.GOES.HERE

Next, enter the following command to enable the Vivado hardware server:

hw_server

Back within Vivado, type the following in the GUI's XSCT console to connect to the remote hardware server (with the appropriate IP):

connect_hw_server -url SERVER.IP.GOES.HERE

Once connected, you should be in the Hardware Manager. Open it if not, then right click the board and select Open Target. The board should be visible in Hardware under the connected IP value.
Select Program Device, select the exported bitstream file from earlier, and the exported .ltx file from the debug build. It should be in the project folder under projectname.runs/impl_1/ and was generated with the Set Up Debug wizard, during Implementation. Click Program.
If all debug probes look good, go to File > Export > Export Hardware. Export a Fixed Platform, and Include Bitstream.
Now, go to Tools > Launch Vitis IDE. Leave Vivado and its Synthesis/Debug view open.

Note: Failing to properly close hw_server on the remote machine can cause issues with trying to start a new instance of hw_server. If you get the error Cannot create listening port: Socket bind error. Address already in use, do the following to kill the process on the remote machine (assuming Linux), replacing 9085 here with the PID value returned with pidof:

pidof hw_server

kill -9 9085 # Replace 9085 with the correct PID value.

Configuring Vitis for Hardware/ILA Debug

The cleanest way to do this is open a new workspace each time, since this avoids (and even fixes) numerous errors and snags that can occur. Typical method is to use the same folder but delete all contents prior to opening - you can also choose a new workspace each time if preferred. Once the workspace folder is selected, click Launch.
Click File > New > New Application Project. Go to the Create a new platform from hardware (XSA) tab and load in the exported .xsa hardware file. Load the Hello World template and click Finish.
In the bottom left Explorer panel, right click the <app_project_name>_system entry (should be second from the top) and click Build Project. This generates the necessary build files.
Click the arrow next to the bug icon ("debug") and select Debug Configurations. Double click Single Application Debug to create a custom debug application.
In the Main tab, choose the appropriate connection. You may need to create a New one if the board is not local. The connection will save its variables even if you clear the workspace, but this needs to be selected each time.
In the Target Setup tab, make sure all of the reset, program and run checkboxes are enabled (not Skip Revision Check) and then also Enable Cross Triggering. Modify this by clicking the ... button.
For Cross Trigger Breakpoints, create two. First, select CPU-0 > CPU0 DBGACK in the left tab, and the entirety of FTM on the right.
For the second breakpoint, select CPU-0 > CPU0 debug request on the right, and the entirety of FTM on the left.
Now click Debug to close the Debug Configurations window.
At the arrow next to the bug icon again, click Debug As and select the configuration that was just generated. The FPGA should program, restart, and run.

Debugging the Hardware with ILA and Register Read/Write

Back in Vivado, click Window > Debug Probes. The play button can be used to set up triggers that will configure it to read the waveform when the conditions are met (typically, you can set a valid signal low-to-high (R) to trigger for AXI signals). The double arrow symbol can be used to immediately show the waveform at the current moment regardless of triggers.

In Vitis, the memory window on the left side can be used to view memory addresses. Using the following commands allows you to read and write from these registers, which in turn will correspond with the registers in your design (which is currently running on the hardware itself) if the address is mapped properly.

Example read command (can use -force flag if the register is protected):

mrd 0x50000000

Example write command (writes a hex value of 1 to addr 5000_0000):

mwr 0x50000000 0x00000001

While debugging with the ILA, pay attention to set up and hold time violations as well as clock domain crossing issues. Both are beyond the scope of this guide.

Debugging the Software with Vitis and the Integrated Logic Analyzer (ILA)

Create a New Application Project in Vitis as before, but set it as a blank C++ application and not Hello World. Add your software code in Vitis and build. The debugging tools are similar to the Eclipse IDE in that you can set breakpoints and view the machine code in Disassembly view.

Assuming the hardware is connected via remote hw_server, you will need to open up a second terminal into that server. Set up minicom and connect to the board via UART (you will need a UART-to-USB connection in addition to the JTAG-to-USB connection) over 115200 baud, 8N1 and clear out modem settings A through H. This is typically /dev/ttyUSB0 or some increment thereof. Any print outputs triggered by the C++ code in Vitis will be displayed over this terminal. Continue to modify code, rebuild the Application Project, and run as needed.

Code Examples

The following is listed here as a quick reference for creating register manipulation debug code.

AXI-4 Interface Protocol

For Xilinx devices, the AXI-4 interface is a common data transfer method between FPGA modules. The AXI-4 Lite protocol (most common) will typically load a correct series of values on the master side, and set valid to high when done. The slave side will set ready high, and this handshake will allow a single burst of (typically 32-bit) data to transfer. The full AXI functionality adds burst and data protection (prot) and is outside the scope of the below snippet, but below will work on both AXI-4 and AXI-4 Lite.

For a system controlled by AXI interfaces, the FPGA will map these interfaces to registers. For example, 0x8000_0000 and 0x8001_0000 may be mapped as the base addresses to two AXI registers, and the registers can both be written to directly from software by using commands such as what is shown below. The system automatically handles all of the handshakes required, so the programmer only has to worry about mapping the register and then reading or writing to it.

Without an OS (Vitis)

void axi_write_phase(u32 writeValue){
                Xil_Out32(AXI_SDR_ADDR, writeValue);
}

Re-Configuring the Integrated Logic Analyzer

When adding and removing debug cores, the design can end up getting buggy. Some notes on fixing:

When adding nets, it is easy to mark them in netlist view (Right click > Mark for Debug) and add them this way. When needing to debug a different set of nets, clear out the target constraints file of all synthesis-added parameters (these will be appended to the file and were for the debug cores). Then close the project and delete the <project_name>.hw and <project_name>.runs folders. This forces the project to do a clean synthesis, at which point you can add new debug cores. Then build as normal.

Debugging Workflow on OS

Once the JTAG debug process has been proven functional, and the design is intended to run with an OS on the SoM, the next step is to build the software code on the OS and run it. To do this, the FPGA will need to be booted from an SD card containing both the firmware and the OS. Previously, it has been booting from JTAG.

(Note: Creating and setting up a bootable OS is beyond the scope of this guide).

Once the necessary files are loaded onto the SD card, ensure the boot select pins on the board are set to SD rather than JTAG, and power up the board. You can use minicom over USB to log in initially, and once SSH is set up, use SSH to enter the board and copy the necessary files over. QPSI-flash (Quad SPI) will need to be set up to allow persistence after boot. Software files should be built on the board itself, and then ran.

Code for writing to registers on Linux is shown below for reference. From this point on, a designer will likely be manipulating registers from software and possibly setting up logging functionality to run on the processor.

With an OS (Running C/C++ Code on a Linux OS on the Zynq Processor)

void axi_write_phase(uint32_t writeValue){
                /* Map the memory */
                int fd = open("/dev/mem", O_RDWR|O_SYNC); // Need to close this when finished to avoid memory issues.
                /* Map the SDR regs */
                void *mm_sdr = mmap(0, 4096, PROT_READ | PROT_WRITE, MAP_SHARED, fd, AXI_SDR_ADDR);
                volatile int *sdr_regs = (volatile int *)mm_sdr;
                *(sdr_regs+0) = (writeValue);
}

Note: For the above, you will eventually need something to close the file descriptor, such as:

munmap(mm_sdr, 4096);
close(fd);

Conclusion

That summarizes the general implementation and debug workflow from post-synthesis to on-hardware implementation. Please feel free to reach out if you find any mistakes or inaccuracies in this guide.

Acronyms

APU: Application Processing Unit
RPU: Real-Time Processing Unit
RTL: Register Transfer Level
HLS: High Level Synthesis
PLL: Phase-Locked Loop
MMCM: Mixed-Mode Clock Manager
RAM: Random Access Memory
DMA: Direct Memory Access
ADC: Analog to Digital Converter
DAC: Digital to Analog Converter
FPGA: Field Programmable Gate Array
MPSoC: Multi Processor System on Chip
DDR: Double Data Rate
SoM: System On Module
QoR: Quality of Results

Setting Up a WireGuard VPN Client on Linux

Joshua Rothe — Sun, 28 Sep 2025 01:35:12 +0000

Full text can also be viewed here.

Setting up a WireGuard VPN for privacy and security involves setting up both server and client side systems. This guide explains how to set up a client side Linux system - with or without Pi-hole DNS filtering on the home network - and then configure the system so that WireGuard settings will switch depending on if the client system is on the home network or not. This is necessary because the WireGuard client will break your network connection if you are on your home network, and there is no need to manually switch your VPN client on and off when automation exists.

This guide assumes a WireGuard VPN server is set up, and port forwarding is configured on the home router (UDP, port 51820 should be forwarding to your WireGuard server). This guide is also written for Linux Mint - while this should also work for most Debian systems, you may need to modify some file paths depending on your distro.

Note: This post was updated Oct 18 2025 to fix two critical issues with the original approach: the WireGuard client would break upon switching network types while the client was shut down, and it did not check if the WireGuard server itself was reachable when on an external network prior to enabling. This improved method fixes these issues and keeps the WireGuard client disabled until the following is verified:

The client is not on the home network.
The WireGuard server is reachable.

The old method is kept in the Appendix for historical purposes, but is depreciated.

Background

VPNs are a great tool for security and privacy, with key benefits being:

Privacy and Security:

Location Privacy: All traffic appears to be from your home IP address. Your actual location is obscured to anyone tracking your browsing activity.
Data Protection: On public wireless networks, your VPN tunnel ensures packet sniffers and other malicious actors can't see your activity.
Audited: WireGuard is open source and is audited regularly by both organizations and individuals. All of its code is viewable by any developer curious enough to know how it functions.

Functionality:

Ad Blocking: If you run a Pi-Hole system at home for ad blocking, you can use that same tool while off your home network.
Home Network Access: This secure tunnel to your home network means you can access devices on your home network such as cameras, NAS systems, and IoT devices without needing to expose them to the internet.
Speed: WireGuard is fast, faster than most other comparable VPN services.

Practicality:

Low Overhead: Works on virtually all modern hardware.
Cryptographically Secure: Uses proven, modern cryptographic primitives detailed on the WireGuard homepage.
Free: Self explanatory. No risk of subscription fees in the future, either. Open source comes with benefits!

If you do not have a WireGuard VPN server set up and find this interesting, I've worked through the official WireGuard documentation and found it more than sufficient. Make sure this is complete before setting up clients! Windows and MacOS have dedicated programs for clients, but Linux is a bit more complicated; hence this guide.

Prerequisites

WireGuard server, configured with port forwarding on your home router.
Linux client with sudo access (tested here on Mint/Debian).
Basic command line familiarity.

Client Setup

SSH Key Generation

This process should be familiar (for general server access, not WireGuard-specific handshakes), but direction is provided below just in case. On the client, run:

ssh-keygen -t ed25519 -C "your-email@example.com"

Hit enter twice - use default location and no passkey (unless you really want one).

There are two ways to copy your key to the server, the Easy Way and the More Likely Way.

The Easy Way:

The easy way only works if your client can access the server. Since we are generating keys, you should probably have password authentication enabled for SSH. In case you forgot, you modify these lines in /etc/ssh/sshd_config:

PasswordAuthentication no
PubkeyAuthentication yes
PermitRootLogin no

Then on the client side you can simply run:

ssh-copy-id username@server-ip

This copies SSH key settings to the host, if security settings allow it.

The More Likely Way:

Run this on the client:

cat ~/.ssh/id_ed25519.pub

Get this clipboard item to the server however you like, probably using another system that does have SSH access, and append it to ~/.ssh/authorized_keys. No need to disable the server's security requirements this way.

Installation

Run on the client to install necessary dependencies:

sudo apt update
sudo apt install wireguard resolvconf netcat-openbsd

Once that is done, generate WireGuard keys (these are different than SSH keys - the former are needed to access the WireGuard server for configuration):

cd /etc/wireguard
sudo umask 077
sudo wg genkey | sudo tee privatekey | sudo wg pubkey | sudo tee publickey

Next, create the WireGuard config file on your client using:

sudo vim /etc/wireguard/wg0.conf

And insert the following text to create your client's WireGuard network configuration file. This facilitates the key handshake your client system will do with the server:

[Interface]
PrivateKey = # Paste the contents of /etc/wireguard/privatekey here
Address = 10.0.0.2/24
DNS = 1.1.1.1
MTU = 1200

[Peer]
PublicKey = # Your server's public key goes here.
Endpoint = your-server-ip:51820
AllowedIPs = 192.168.1.0/24, 10.0.0.0/24
PersistentKeepalive = 25

Note that you have three items to fill in above. You will need the PublicKey from the server, not from what you have here on the client. So hold off on that for now.

MTU is optional, but I found that on Xfinity's public network it is necessary. A niche problem I spent a while debugging before finding the solution. The split tunneling at AllowedIPs only routes home traffic through your home network, so you can access cameras and local infrastructure. All other traffic will not route through the VPN - this is much faster and best practice. If slow speed is OK or all traffic needs to route through the VPN for some other reason, AllowedIPs can be 0.0.0.0/0.

The private key on the client can be acquired using:

sudo cat /etc/wireguard/privatekey

The public key on the client (which will be needed on the server) can be acquired using:

sudo cat /etc/wireguard/publickey

Now SSH into the WireGuard server, and edit the WireGuard config using:

sudo vim /etc/wireguard/wg0.conf

Append the following to the file:

[Peer]
PublicKey = # Paste your client's public key here.
AllowedIPs = 10.0.0.x/32

For AllowedIPs, you will need to replace the x. For my setup, the server was .1, and I had two previous clients taking up .2 and .3, so I used .4. These are the IPs the WireGuard server uses to identify the peers on its network.

Back on the client, edit the client's WireGuard config using:

sudo vim /etc/wireguard/wg0.conf

Remember how we didn't have the server's public key last time? Fix that now:

[Interface]
PrivateKey = # Paste(d) the contents of /etc/wireguard/privatekey here
Address = 10.0.0.2/24
DNS = 1.1.1.1
MTU = 1200

[Peer]
PublicKey = # Your server's public key goes here.
Endpoint = your-server-ip:51820
AllowedIPs = 192.168.1.0/24, 10.0.0.0/24
PersistentKeepalive = 25

Three items to check, above. Make sure the Address on your client side matches AllowedIps on the server side.

Automated VPN Management

Run this first to set the WireGuard client as disabled by default:

sudo systemctl disable wg-quick@wg0
sudo systemctl stop wg-quick@wg0

Run:

sudo vim /etc/NetworkManager/dispatcher.d/99-wireguard-auto

Replace the script text with the following, adjusting the HOME_* values as needed:

#!/bin/bash

INTERFACE=$1
ACTION=$2

# Configuration. Change these as needed.
HOME_NETWORK_GATEWAY="192.168.1.1" # Router's IP.
HOME_WIREGUARD_SERVER="192.168.1.114" # WireGuard server IP.
WIREGUARD_PORT="51820"
HOME_EXTERNAL_IP="YOUR.EXTERNAL.IP" # Your external home network IP.
LOG_FILE="/var/log/wireguard-auto.log"

PING_TIMEOUT=5
NC_TIMEOUT=10

log_message() {
    echo "$(date): [$INTERFACE/$ACTION] $1" | tee -a "$LOG_FILE"
}

is_wireguard_server_reachable() {
    local server_ip="$1"
    local port="$2"

    if command -v nc >/dev/null 2>&1; then
        if nc -u -z -w 5 "$server_ip" "$port" >/dev/null 2>&1; then
            log_message "Server $server_ip is reachable and responding"
            return 0
        else
            log_message "WireGuard port $port on $server_ip is not responding"
            return 1
        fi
    else
        # Fallback if nc is not available.
        log_message "Error: nc not available"
        return 1
    fi
}

is_home_network() {
    if ping -c 3 -W "$PING_TIMEOUT" "$HOME_NETWORK_GATEWAY" >/dev/null 2>&1; then
        if ping -c 3 -W "$PING_TIMEOUT" "$HOME_WIREGUARD_SERVER" >/dev/null 2>&1; then
            local_ip=$(ip route get 8.8.8.8 2>/dev/null | awk '{print $7; exit}')
            if [[ "$local_ip" =~ ^192\.168\.1\. ]]; then
                return 0
            fi
        fi
    fi
    return 1
}

enable_wireguard() {
    if ! systemctl is-active --quiet wg-quick@wg0; then
        log_message "Enabling WireGuard"
        systemctl enable wg-quick@wg0
        systemctl start wg-quick@wg0
    fi
}

disable_wireguard() {
    if systemctl is-active --quiet wg-quick@wg0; then
        log_message "Disabling WireGuard"
        systemctl disable wg-quick@wg0
        systemctl stop wg-quick@wg0
    fi
}

# Only act on interface up events.
if [ "$2" != "up" ]; then
    exit 0
fi

log_message "Network change detected on $1"

sleep 10

if is_home_network; then
    log_message "Home network confirmed - ensuring WireGuard is disabled"
    disable_wireguard
else
    log_message "External network confirmed - testing VPN server"
    if is_wireguard_server_reachable "$HOME_EXTERNAL_IP" "$WIREGUARD_PORT"; then
        log_message "VPN server reachable - enabling WireGuard"
        enable_wireguard
    else
        log_message "VPN server unreachable - WireGuard remains disabled"
        disable_wireguard
    fi
fi

Next, run sudo vim /etc/systemd/system/wireguard-boot-check.service and add:

[Unit]
Description=WireGuard Boot Config
After=network-online.target
Wants=network-online.target
Before=wg-quick@wg0.service

[Service]
Type=oneshot
ExecStart=/usr/local/bin/wireguard-boot-check.sh
RemainAfterExit=yes
TimeoutStartSec=150

[Install]
WantedBy=multi-user.target

Then run sudo vim /usr/local/bin/wireguard-boot-check.sh and add the following adjusting variables as needed:

#!/bin/bash

# Configuration - adjust these to match your setup.
HOME_NETWORK_GATEWAY="192.168.1.1"
HOME_WIREGUARD_SERVER="192.168.1.114"
HOME_EXTERNAL_IP="YOUR.EXTERNAL.IP.HERE"
WIREGUARD_PORT="51820"
LOG_FILE="/var/log/wireguard-boot-check.log"

# Timeout after 2 min.
NETWORK_WAIT_TIMEOUT=120
PING_TIMEOUT=5
NC_TIMEOUT=10

log_message() {
    echo "$(date): $1" | tee -a "$LOG_FILE"
}

is_wireguard_server_reachable() {
    local server_ip="$1"
    local port="$2"

    # Give network time to settle on boot.
    sleep 10
    check_timeout

    if command -v nc >/dev/null 2>&1; then
        if nc -u -z -w 5 "$server_ip" "$port" >/dev/null 2>&1; then
            log_message "Server $server_ip is reachable and responding"
            return 0
        else
            log_message "WireGuard port $port on $server_ip is not responding"
            return 1
        fi
    else
        # Fallback if nc is not available.
        log_message "Error: nc not available"
        return 1
    fi
}

is_home_network() {
    # Check if home gateway is reachable.
    if ping -c 3 -W "$PING_TIMEOUT" "$HOME_NETWORK_GATEWAY" >/dev/null 2>&1; then
        # Second check by pinging WireGuard server directly.
        if ping -c 3 -W "$PING_TIMEOUT" "$HOME_WIREGUARD_SERVER" >/dev/null 2>&1; then
            # Third check by seeing if client IP is in the home range.
            local_ip=$(ip route get 8.8.8.8 2>/dev/null | awk '{print $7; exit}')
            if [[ "$local_ip" =~ ^192\.168\.1\. ]]; then
                log_message "Confirmed home network (gateway: $HOME_NETWORK_GATEWAY, server: $HOME_WIREGUARD_SERVER, local IP: $local_ip)"
                return 0
            fi
        fi
    fi
    log_message "Not on home network"
    return 1
}

enable_wireguard() {
    log_message "Enabling WireGuard"
    systemctl enable wg-quick@wg0
    systemctl start wg-quick@wg0
}

log_message "Boot check: Starting (WireGuard disabled by default)"

# Wait for stable network connectivity.
elapsed=0
while [ $elapsed -lt $NETWORK_WAIT_TIMEOUT ]; do
    if ping -c 2 -W 3 8.8.8.8 >/dev/null 2>&1; then
        log_message "Network connectivity established after ${elapsed}s"
        break
    fi
    log_message "Waiting for network connectivity... (${elapsed}s)"
    sleep 10
    elapsed=$((elapsed + 10))
done

# If still no connectivity, exit.
if ! ping -c 2 -W 3 8.8.8.8 >/dev/null 2>&1; then
    log_message "No network connectivity after ${elapsed}s - WireGuard remains disabled"
    exit 0
fi

log_message "Allowing network to settle..."
sleep 15

# Network location detection.
if is_home_network; then
    log_message "Home network confirmed - WireGuard remains disabled"
else
    log_message "External network confirmed - testing VPN server accessibility"
    if is_wireguard_server_reachable "$HOME_EXTERNAL_IP" "$WIREGUARD_PORT"; then
        log_message "VPN server confirmed reachable - enabling WireGuard"
        enable_wireguard
    else
        log_message "VPN server not accessible - WireGuard remains disabled"
    fi
fi

log_message "Boot check: WireGuard configuration complete"

Make the script executable and enable it.

sudo chmod +x /usr/local/bin/wireguard-boot-check.sh
sudo systemctl enable wireguard-boot-check.service

Lastly, run:

sudo vim /etc/wireguard/wg0.conf

And add this to the file:

[Interface]
PrivateKey = # Your laptop's private key.
Address = 10.0.0.2/24
DNS = 1.1.1.1 # Or 192.168.1.xxx for Pi-Hole.

[Peer]
PublicKey = # Your server's public key.
Endpoint = your-server-external-ip:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

Note for Endpoint above, you need your server's external IP. This will be your home router's IP, port forwarded to your VPN server.

Verification

After setup is complete, verify your VPN is working correctly.

On an 'away' network, run:

sudo wg show
sudo systemctl status wg-quick@wg0
ip addr show wg0

You should see your WireGuard client configuration in the output.

You should also see your home external IP displayed when you try to view your client's public IP. Verify this using:

curl -s ifconfig.me

Verify DNS resolution using:

nslookup google.com

The logs should also populate as your client switches networks or reboots. This can be viewed using:

sudo tail -f /var/log/wireguard-auto.log
sudo tail -f /var/log/wireguard-boot-check.log

Conclusion

That should get you a working VPN client! If you notice any issues with this guide, please feel free to reach out or leave a comment.

Appendix

The old (depreciated) method can be viewed here.