DEV Community

MAHER X
MAHER X

Posted on

How to Use Uqda Network: A Complete Step-by-Step Guide 🚀

#networking #privacy #cybersecurity #opensource

How to Use Uqda Network: A Complete Step-by-Step Guide 🚀

Want to join an encrypted mesh network but don't know where to start? This guide will walk you through everything you need to know to get Uqda Network up and running on your device.

Uqda Network is an end-to-end encrypted IPv6 mesh network that gives you a permanent address, automatic encryption, and a self-healing network—all without central servers or complex configuration.

In this guide, we'll cover everything from downloading and installing Uqda to connecting to peers and using your network. Let's get started!

What You'll Need

Before we begin, make sure you have:

  • A computer running Windows, macOS, or Linux
  • Administrator or root access (needed to create network interfaces)
  • An internet connection
  • About 5-10 minutes of your time

That's it! No special hardware, no complex setup, no technical expertise required.

Step 1: Download Uqda

Visit the Releases Page

Go to the Uqda Core releases page on GitHub. You'll see a list of available versions and download options.

Choose Your Platform

For Windows:

  • Look for files ending in .msi
  • Choose x64 for 64-bit Windows or arm64 for ARM-based Windows devices
  • The file will be named something like Uqda-*-x64.msi

For macOS:

  • Look for files ending in .pkg
  • Choose arm64 for Apple Silicon (M1, M2, M3) or amd64 for Intel Macs
  • The file will be named something like Uqda-*-macos-arm64.pkg

For Linux (Debian/Ubuntu):

  • Look for files ending in .deb
  • Choose amd64 for 64-bit systems or arm64 for ARM-based systems
  • The file will be named something like Uqda-*-amd64.deb

Download the File

Click on the file to download it. The download should only take a few seconds as the installer is relatively small.

Step 2: Install Uqda

Windows Installation

  1. Locate the downloaded file in your Downloads folder
  2. Double-click the .msi file to start the installer
  3. Follow the installation wizard:
    • Click "Next" on the welcome screen
    • Accept the license agreement
    • Choose installation location (default is fine)
    • Click "Install"
  4. Wait for installation to complete (usually takes less than a minute)
  5. Click "Finish" when done

The installer will automatically:

  • Install the Uqda binaries
  • Set up the Windows service
  • Create necessary directories
  • Configure the service to start automatically

macOS Installation

  1. Locate the downloaded file in your Downloads folder
  2. Double-click the .pkg file to start the installer
  3. Follow the installation prompts:
    • Click "Continue" on the introduction screen
    • Read and accept the license agreement
    • Choose installation location (default is fine)
    • Enter your administrator password when prompted
    • Click "Install"
  4. Wait for installation to complete
  5. Click "Close" when done

The installer will automatically:

  • Install Uqda to the system directory
  • Set up the launchd service
  • Create configuration directories
  • Prepare the service for startup

Linux Installation

Method 1: Using the Package Manager (Recommended)

  1. Open Terminal
  2. Navigate to your Downloads folder:
    • Type: cd ~/Downloads
  3. Install the package:
    • Type: sudo dpkg -i Uqda-*.deb
    • Replace * with the actual version number in your file name
    • Enter your password when prompted
  4. If there are dependency issues, fix them:
    • Type: sudo apt-get install -f
  5. Wait for installation to complete

Method 2: Using the GUI

  1. Locate the downloaded file in your file manager
  2. Double-click the .deb file
  3. Your package manager will open (Software Center, GDebi, etc.)
  4. Click "Install" and enter your password
  5. Wait for installation to complete

The installer will automatically:

  • Install Uqda binaries to system directories
  • Set up systemd service files
  • Create configuration directories
  • Prepare the service for automatic startup

Step 3: Start the Service

Windows

  1. Open Command Prompt as Administrator:

    • Press Windows Key + X
    • Select "Windows PowerShell (Admin)" or "Command Prompt (Admin)"
    • Click "Yes" when prompted by User Account Control

  2. Start the service:

    • Type: net start uqda
    • Press Enter

  3. Verify it's running:

    • The service should start without errors
    • You can check the service status in Windows Services if needed

The service will now run in the background and start automatically on boot.

macOS

  1. Open Terminal

  2. Start Uqda with auto-configuration:

    • Type: sudo uqda -autoconf
    • Press Enter
    • Enter your administrator password when prompted

  3. Verify it's running:

    • You should see output indicating the service has started
    • The service will continue running in the background

The service will start automatically on system boot.

Linux

  1. Open Terminal

  2. Start the service:

    • Type: sudo systemctl start uqda
    • Press Enter
    • Enter your password when prompted

  3. Enable automatic startup (optional but recommended):

    • Type: sudo systemctl enable uqda
    • Press Enter

  4. Check the service status:

    • Type: sudo systemctl status uqda
    • You should see "active (running)" in green

The service will now run automatically on boot.

Step 4: Get Your Uqda Address

Once the service is running, you need to find your permanent Uqda IPv6 address.

Using the Control Tool

On Windows:

  1. Open Command Prompt (regular, not admin)
  2. Navigate to the Uqda installation directory (usually C:\Program Files\Uqda)
  3. Type: uqdactl getSelf
  4. Look for the "IPv6 address" line

On macOS and Linux:

  1. Open Terminal
  2. Type: uqdactl getSelf
  3. Look for the "IPv6 address" line

What You'll See

You'll see output like this:

Build name:             Uqda-v0.1.0
Build version:          0.1.0
IPv6 address:           200:5d86:87e1:4b3b:bcfe:833d:3c87:94bf
IPv6 subnet:            300:5d86:87e1:4b3b::/64
Routing table size:     5
Public key:             d13cbc0f5a622180be6161bc35a0025d17cef992acae066cf084cc3c5da3fc4a
Enter fullscreen mode Exit fullscreen mode

Important: Your IPv6 address (the one starting with 200:) is your permanent address. Write it down or save it somewhere safe—you'll need it to connect to other devices and services.

Step 5: Connect to Peers

To join the Uqda network, you need to connect to at least one peer. A peer is another Uqda node that's already on the network.

Option A: Use Public Peers

Many community members share their peer addresses publicly. These are great for getting started.

  1. Find public peers:

    • Check the Uqda GitHub repository
    • Look for community-maintained peer lists
    • Search for "Uqda public peers" online

  2. Add a peer:

    • Use the control tool: uqdactl addPeer tcp://example.com:12345
    • Replace the address with an actual public peer address
    • You can add multiple peers for better connectivity

  3. Verify connection:

    • Type: uqdactl getPeers
    • You should see your peer listed with status "Up"

Option B: Connect to Friends

If you know someone running Uqda:

  1. Exchange addresses:

    • Share your Uqda IPv6 address with them
    • Get their peer connection address (usually a TCP or TLS address)

  2. Add each other:

    • Use: uqdactl addPeer tcp://their-server.com:port
    • They should add your address too

  3. Verify connection:

    • Check with: uqdactl getPeers
    • You should see each other in the peer list

Option C: Auto-Discovery

If you're on the same local network as other Uqda nodes:

  1. Enable multicast (if available):

    • Uqda can automatically discover peers on your local network
    • No manual configuration needed

  2. Check discovered peers:

    • Use: uqdactl getPeers
    • Local peers should appear automatically

Adding Peers to Configuration (Permanent)

To make peer connections permanent (so they survive reboots):

  1. Generate or edit your configuration:

    • Type: uqda -genconf > uqda.conf (if you don't have one)
    • Or edit your existing configuration file

  2. Add peers to the configuration:

    • Find the "Peers" section
    • Add peer addresses in the format: tcp://example.com:12345

  3. Restart the service:

    • The peers will be loaded from the configuration file
    • They'll reconnect automatically on startup

Step 6: Verify Your Connection

Now that you're connected to peers, let's verify everything is working.

Check Peer Status

Type: uqdactl getPeers

You should see:

  • Your connected peers listed
  • Their connection status (should be "Up")
  • Connection statistics (uptime, data transferred, etc.)

Check Your Network Information

Type: uqdactl getSelf

You should see:

  • Your IPv6 address
  • Your subnet
  • Routing table size (should be greater than 0 if connected)
  • Your public key

Test Connectivity

Try pinging another Uqda node:

  • Use: ping6 200:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx
  • Replace with an actual Uqda IPv6 address
  • You should get responses if the network is working

Step 7: Use Your Network

Now that you're connected, you can start using your Uqda network!

Access Services

Any application that supports IPv6 can use Uqda addresses:

  • Web servers: Access websites running on Uqda addresses
  • SSH: Connect to remote servers using their Uqda addresses
  • File sharing: Use any file-sharing app with Uqda addresses
  • Gaming: Connect to game servers on Uqda addresses

Share Your Address

You can share your Uqda IPv6 address with others so they can:

  • Connect to services you're running
  • Access your network resources
  • Communicate with you securely

Run Services

You can run services on your Uqda address:

  • Web servers
  • File servers
  • Game servers
  • Any network service that supports IPv6

Just bind your service to your Uqda IPv6 address instead of your regular IP address.

Managing Your Network

View Network Statistics

Check peer connections:

  • uqdactl getPeers - See all connected peers and their status

View routing information:

  • uqdactl getTree - See the network routing tree
  • uqdactl getSessions - See active network sessions

Monitor network activity:

  • Check peer statistics (data transferred, uptime, latency)
  • Monitor routing table size
  • Watch for connection issues

Add or Remove Peers

Add a new peer:

  • uqdactl addPeer tcp://example.com:12345
  • Or use the shortcut: uqdactl add tcp://example.com:12345

Remove a peer:

  • uqdactl removePeer tcp://example.com:12345
  • Or use the shortcut: uqdactl remove tcp://example.com:12345

Make changes permanent:

  • Add or remove peers from your configuration file
  • Restart the service to apply changes

Update Configuration

Generate a new configuration:

  • uqda -genconf > new-uqda.conf
  • This creates a fresh configuration with new keys

Edit existing configuration:

  • Open your configuration file in a text editor
  • Make your changes
  • Restart the service to apply

Backup your configuration:

  • Your configuration file contains your private keys
  • Back it up securely
  • Without it, you'll lose your permanent address

Common Use Cases

Personal Use

Secure browsing:

  • All your traffic is encrypted automatically
  • Your real IP address is hidden
  • Perfect for public Wi-Fi

Access home network:

  • Connect to your home devices from anywhere
  • Use your permanent Uqda address
  • No need to expose ports to the internet

Private file sharing:

  • Share files with friends securely
  • All traffic is encrypted
  • Direct peer-to-peer connections

Professional Use

Remote access:

  • Securely access work resources
  • No VPN servers needed
  • Direct encrypted connections

Team collaboration:

  • Connect distributed teams
  • Share resources privately
  • Build private infrastructure

Development:

  • Test applications on encrypted networks
  • Build decentralized services
  • Create private development environments

Community Use

Local mesh networks:

  • Build community networks
  • Work even if internet goes down (for local traffic)
  • Community-owned infrastructure

Resource sharing:

  • Share internet connections
  • Distribute content locally
  • Build resilient networks

Tips for Best Experience

Security Best Practices

Protect your keys:

  • Your configuration file contains your private keys
  • Keep it secure and backed up
  • Don't share it with anyone

Use TLS peers:

  • When possible, connect to peers using TLS
  • Adds extra encryption layer
  • Especially important for public peers

Trust your peers:

  • Only connect to peers you trust
  • Be cautious with public peer lists
  • Verify peer addresses before connecting

Performance Optimization

Connect to multiple peers:

  • More peers = better connectivity
  • Redundancy improves reliability
  • Network routes around failures automatically

Choose nearby peers:

  • Lower latency with closer peers
  • Better performance
  • Still works with distant peers, just slower

Monitor your network:

  • Check connection status regularly
  • Remove slow or unreliable peers
  • Add new peers as needed

Maintenance

Keep software updated:

  • New versions include security fixes
  • Performance improvements
  • New features

Regular backups:

  • Backup your configuration file
  • Keep multiple copies
  • Store securely

Monitor logs:

  • Check service logs for issues
  • Look for connection problems
  • Debug network issues

Troubleshooting

Service Won't Start

Windows:

  • Make sure you're running as Administrator
  • Check Windows Services for error messages
  • Verify the service is installed correctly

macOS:

  • Make sure you have administrator privileges
  • Check system logs for errors
  • Verify installation completed successfully

Linux:

  • Check service status: sudo systemctl status uqda
  • View logs: sudo journalctl -u uqda
  • Verify permissions and configuration

Can't Connect to Peers

Check peer address:

  • Verify the address is correct
  • Make sure the peer is online
  • Try different peers

Firewall issues:

  • Check that your firewall allows the connection
  • Verify ports are open
  • Test with firewall temporarily disabled

Network issues:

  • Check your internet connection
  • Verify DNS resolution works
  • Try connecting from a different network

Slow Performance

Add more peers:

  • More peers provide better routing
  • Redundancy improves performance
  • Try peers in different locations

Check your connection:

  • Verify your internet speed
  • Check for network congestion
  • Test with different peers

Optimize configuration:

  • Remove slow peers
  • Add faster peers
  • Adjust network settings if needed

Address Not Working

Verify service is running:

  • Check service status
  • Restart if needed
  • Check for error messages

Check peer connections:

  • Make sure you're connected to peers
  • Verify peer status is "Up"
  • Try reconnecting to peers

Application support:

  • Make sure your application supports IPv6
  • Check application configuration
  • Test with IPv6-capable tools

Getting Help

If you run into issues:

Check the documentation:

  • Read the README on GitHub
  • Look for troubleshooting guides
  • Search for known issues

Community support:

  • Open an issue on GitHub
  • Ask questions in discussions
  • Check existing issues for solutions

Contact:

Next Steps

Now that you're up and running:

  1. Explore the network: Try connecting to different services
  2. Share with friends: Help others get started
  3. Build something: Create services on your Uqda address
  4. Join the community: Contribute and help improve Uqda

Conclusion

Congratulations! You've successfully set up and connected to Uqda Network. You now have:

  • A permanent IPv6 address
  • Automatic encryption for all traffic
  • Access to a global mesh network
  • Control over your network identity

Uqda Network gives you privacy, security, and freedom on the internet. Enjoy your new encrypted network!

Made with ❤️ for a more private internet

Resources:

Have questions? Drop a comment below! Need help? We're here for you! 🚀

Top comments (0)