Network Configuration

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:

Configure Port Range

[server]
portrange = [2234, 2234]

Format: [min_port, max_port]Use the same value for both to bind to a specific port.

Set via Command Line

nicotine --port 2234

Command line arguments override config settings.

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:

Automatic forwarding using UPnP/NAT-PMP (recommended)
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:

Set Interface IP

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

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

Override via CLI

nicotine --bindip 10.8.0.1

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

Discovery

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

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

Renewal

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

Protocol Priority

NAT-PMP - Tried first (faster, simpler)
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:

Use VPN provider’s port forwarding (if available)
Manual port forward on exit node
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:

Find Your Local IP

# Linux
ip addr show | grep "inet "

# Windows
ipconfig | findstr IPv4

Access Router Admin

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

Create Port Forward

Add a port forwarding rule:

Protocol: TCP
External Port: 2234
Internal IP: Your local IP
Internal Port: 2234
Description: Nicotine+

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.