Network Configuration

Configure network settings, ports, interfaces, UPnP, and connection behavior

Proper network configuration is essential for Nicotine+ to connect to the Soulseek network and accept incoming connections for file transfers.

Server Configuration

Server Address

Connect to the official Soulseek server:

[server]
server = ["server.slsknet.org", 2242]

The server address is a tuple containing the hostname and port number.

Authentication

[server]
login = "your_username"
passw = "your_password"

Passwords are stored in plain text. Set restrictive file permissions on your config file:

chmod 600 ~/.config/nicotine/config

Auto-Connect

[server]
auto_connect_startup = True

When enabled, Nicotine+ automatically connects to the server on startup.

Port Configuration

Listening Port

Nicotine+ requires an open TCP port for incoming connections:

1. Configure Port Range

   [server]
   portrange = [2234, 2234]
   

   Format: [min_port, max_port]

   Use the same value for both to bind to a specific port.

2. Set via Command Line

   nicotine --port 2234
   

   Command line arguments override config settings.

3. Verify Port is Open

   After connecting, check your port status in the GUI or visit:

   https://www.slsknet.org/porttest.php?port=2234

If portrange contains different values, Nicotine+ will attempt to bind to a random port within the range.

Common Port Issues

Firewall Blocking

Ensure your firewall allows incoming TCP connections:

Linux (ufw):

sudo ufw allow 2234/tcp

Linux (iptables):

sudo iptables -A INPUT -p tcp --dport 2234 -j ACCEPT

Windows: Add an inbound rule in Windows Defender Firewall for TCP port 2234.

Router NAT

If behind a NAT router, you need either:

1. Automatic forwarding using UPnP/NAT-PMP (recommended)
2. Manual port forwarding in your router settings

Forward external port 2234 → your local IP:2234

Multiple Instances

Running multiple instances requires different ports:

# Instance 1
nicotine --config ~/.config/nicotine/config1 --port 2234

# Instance 2
nicotine --config ~/.config/nicotine/config2 --port 2235

Network Interface Binding

Bind to Specific IP

Useful for VPN connections or multi-homed systems:

1. Set Interface IP

   [server]
   interface = "10.8.0.1"  # VPN interface IP
   

   Leave empty ("") to bind to all interfaces.

2. Override via CLI

   nicotine --bindip 10.8.0.1
   
3. Verify Binding

   Check the debug log to confirm binding:

   Binding socket to local IP address 10.8.0.1
   

When using a VPN, bind to the VPN interface IP to ensure all Nicotine+ traffic routes through the VPN.

Finding Your Interface IP

Linux:

ip addr show
# or
ifconfig

Windows:

ipconfig

Look for the IP address of your desired network interface (e.g., tun0 for VPN, eth0 for ethernet).

UPnP / NAT-PMP

Automatic Port Forwarding

Nicotine+ supports automatic port forwarding using UPnP and NAT-PMP protocols:

[server]
upnp = True
upnp_interval = 4  # Hours between renewal attempts

UPnP automatically configures your router to forward the listening port. This is the easiest way to accept incoming connections.

How It Works

1. Discovery

   Nicotine+ discovers UPnP/NAT-PMP capable routers on your network using multicast discovery.

2. Port Mapping

   Creates a port mapping rule on your router:

   • External port: 2234 (configurable)
   • Internal IP: Your local machine IP
   • Internal port: 2234
   • Protocol: TCP
   • Lease duration: 12 hours
3. Renewal

   Automatically renews the port mapping every 2 hours (before the 12-hour lease expires).

Protocol Priority

1. NAT-PMP - Tried first (faster, simpler)
2. UPnP - Fallback if NAT-PMP unavailable

NAT-PMP Details

• Standard port: UDP 5351
• Request attempts: 2
• Timeout: 0.25 seconds initially, doubles on retry
• Discovers gateway via routing table

# NAT-PMP requests sent to gateway
# Gateway address detected from /proc/net/route (Linux)
# or netstat -rn (BSD/macOS/Windows)

UPnP Details

• Discovery: SSDP multicast to 239.255.255.250:1900
• Supported services:
  • WANIPConnection:2 (preferred)
  • WANIPConnection:1
  • WANPPPConnection:1
• HTTP timeout: 5 seconds
• Multicast TTL: 2

# User agent sent in UPnP requests:
# Python/3.x UPnP/2.0 Nicotine+/3.4.0

Troubleshooting UPnP

If UPnP fails, check the debug log for detailed error messages.

Common Issues:

UPnP Disabled on Router

Enable UPnP in your router’s administration panel. Usually found under:

• Advanced Settings → UPnP
• NAT → UPnP
• Firewall → UPnP

Firewall Blocking Discovery

Ensure your firewall allows:

• Outbound UDP to 239.255.255.250:1900
• Outbound TCP to router’s control URL

# Linux: check if router responds
tcpdump -i any udp port 1900

Multiple Routers / VPN

When using a VPN, UPnP won’t work with your local router. Options:

1. Use VPN provider’s port forwarding (if available)
2. Manual port forward on exit node
3. Accept limited connectivity

Router Compatibility

Some routers only support permanent leases:

UPnP error code 725: OnlyPermanentLeasesSupported

Nicotine+ automatically retries with lease_duration=0.

Manual Port Forwarding

If UPnP is unavailable:

1. Find Your Local IP

   # Linux
   ip addr show | grep "inet "
   
   # Windows
   ipconfig | findstr IPv4
   
2. Access Router Admin

   Navigate to your router’s IP (commonly 192.168.1.1 or 192.168.0.1) in a web browser.

3. Create Port Forward

   Add a port forwarding rule:

   • Protocol: TCP
   • External Port: 2234
   • Internal IP: Your local IP
   • Internal Port: 2234
   • Description: Nicotine+
4. Disable UPnP in Nicotine+

   [server]
   upnp = False
   

Connection Testing

Port Checker

Test if your port is accessible from the internet:

# Official Soulseek port checker
curl "https://www.slsknet.org/porttest.php?port=2234"

Or visit in a browser:

https://www.slsknet.org/porttest.php?port=2234

The port checker URL is defined in pynicotine/__init__.py:

__port_checker_url__ = "https://www.slsknet.org/porttest.php?port=%s"

Debug Network Issues

Enable debug logging to diagnose connection problems:

[logging]
debug = True
debug_file_output = True

Check debug logs for:

• NAT-PMP: Portmap request attempt...
• UPnP: SSDP request sent...
• Binding socket to local IP address...

Advanced Settings

CTCP Messages

[server]
ctcpmsgs = False

Enable Client-To-Client Protocol messages (rarely used).

IP Blocking

Block Specific IPs

[server]
ipblocklist = {
    "192.168.1.100": "Blocked reason",
    "10.0.0.5": "Another reason"
}

Ignore IPs

[server]
ipignorelist = {
    "203.0.113.0": "Ignored"
}

Network Performance

Connection Limits

While not directly configurable in network settings, connection behavior is influenced by:

[transfers]
uploadslots = 2           # Simultaneous upload connections
queuelimit = 10000        # Max queued transfers
filelimit = 100           # Max files per user

See Downloads & Uploads for more details on managing transfers.

Bandwidth Management

Configure upload/download speed limits:

[transfers]
use_upload_speed_limit = "unlimited"    # "unlimited", "primary", "alternative"
uploadlimit = 1000                      # KB/s (primary limit)
uploadlimitalt = 100                    # KB/s (alternative limit)

use_download_speed_limit = "unlimited"
downloadlimit = 1000                    # KB/s
downloadlimitalt = 100                  # KB/s

Use bandwidth limits to prevent Nicotine+ from saturating your connection.

VPN Configuration Example

Complete example for using Nicotine+ with a VPN:

[server]
interface = "10.8.0.1"  # VPN interface IP
portrange = [2234, 2234]
upnp = False            # VPN doesn't support UPnP

# Start Nicotine+ bound to VPN
nicotine --bindip 10.8.0.1

Ensure your VPN provider supports port forwarding. Many VPNs do not allow incoming connections.

Docker / Container Networking

When running in containers:

[server]
interface = ""  # Bind to all interfaces
portrange = [2234, 2234]
upnp = False    # UPnP doesn't work in containers

Docker port mapping:

docker run -p 2234:2234/tcp nicotine

Manually forward port 2234 on your host to the container.

Network Configuration Validation

Verify your configuration:

1. Check Config Values

   Ensure port range is valid:

   # From config.py validation:
   # portrange must be [int, int]
   portrange = [2234, 2234]  # Valid
   
2. Connect to Server

   Successful connection confirms server settings are correct.

3. Test Port Access

   Use the port checker to verify incoming connections work.

4. Monitor Debug Log

   Enable debug logging and watch for network-related messages:

   • Port binding confirmations
   • UPnP/NAT-PMP status
   • Connection attempts