Virtual Printer¶

The Virtual Printer feature allows Bambuddy to emulate a Bambu Lab printer on your network. This enables you to send prints directly from Bambu Studio or Orca Slicer to Bambuddy, even without a physical printer connected.

Overview¶

When enabled, Bambuddy creates a virtual printer that:

• Appears automatically in Bambu Studio/Orca Slicer via SSDP discovery
• Accepts print jobs over secure TLS/MQTT connections
• Archives prints directly or queues them for review
• Works with the same workflow as sending to a real Bambu Lab printer

Use Cases¶

• Print Archiving: Send prints to Bambuddy for archiving without starting them
• Queue Building: Build up a print queue before your printer is available
• Print Farm Preparation: Prepare jobs to distribute across multiple printers
• Remote Slicing: Slice on one computer and send to Bambuddy running elsewhere
• 🌐 Remote Printing: Print from anywhere via Proxy Mode (see below)

Proxy Mode - Remote Printing¶

What is Proxy Mode?¶

Unlike the standard virtual printer modes that archive files locally, Proxy Mode forwards your print jobs directly to a real Bambu Lab printer. Bambuddy acts as a secure relay between your slicer and your printer.

How It Works¶

1. Select the target printer (must be in LAN mode)
2. For cross-network: select the slicer network interface for SSDP relay
3. Enable the proxy - printer appears in slicer discovery via SSDP
4. Connect using the printer's access code
5. Print as normal - traffic is relayed through Bambuddy
6. Camera streaming requires NAT/IP forwarding (see below)

Key Benefits¶

Feature	Description
TLS-encrypted control channels	MQTT and FTP control fully encrypted; use VPN for data channel
No cloud dependency	Your data never touches third-party servers
Uses printer's credentials	No additional passwords - use your printer's access code
Full protocol support	Both FTP (file transfer) and MQTT (control) are proxied
Connection monitoring	Real-time status showing active connections

Proxy Mode Ports¶

Requirements¶

Printer Requirements:

• Bambu Lab printer in LAN Mode (Developer Mode)
• Printer must be accessible from Bambuddy on your local network
• Printer's IP address and access code

Network Requirements:

• Bambuddy server accessible from the internet (or your remote network)
• Ports 990 (FTP control), 8883 (MQTT), and 50000-50100 (FTP data) reachable from the remote slicer
• Static IP or dynamic DNS for your Bambuddy server

Supported Network Configurations:

Network Interface Override (All Modes):

Dual-Homed (Cross-Network) Setup:

For setups where Bambuddy has interfaces on two networks (e.g., printer on LAN A, slicer on LAN B):

• Enable the virtual printer, then select the correct interface under Network Interface Override
• In Proxy mode, Bambuddy will re-broadcast printer SSDP on the slicer's network
• In other modes, SSDP broadcasts and TLS certificates use the selected interface IP
• The slicer discovers the printer automatically via SSDP
• Camera streaming requires additional NAT/iptables rules (RTSP port 322)

Single Interface + Port Forwarding Setup:

For remote access where Bambuddy and printer are on the same network:

• Configure port forwarding on your router (ports 990, 8883, 50000-50100 to Bambuddy)
• Remote user manually adds printer in slicer using Bambuddy's public IP/hostname
• No automatic SSDP discovery (slicer is on a different network)

Setting Up Proxy Mode¶

Step 1: Configure Ports for Your Installation¶

Choose your installation type below:

# UFW
sudo ufw allow 990/tcp comment "Bambuddy Proxy FTP"
sudo ufw allow 8883/tcp comment "Bambuddy Proxy MQTT"
sudo ufw allow 50000:50100/tcp comment "Bambuddy Proxy FTP Data"

# Or firewalld
sudo firewall-cmd --permanent --add-port=990/tcp
sudo firewall-cmd --permanent --add-port=8883/tcp
sudo firewall-cmd --permanent --add-port=50000-50100/tcp
sudo firewall-cmd --reload

services:
  bambuddy:
    image: ghcr.io/maziggy/bambuddy:latest
    container_name: bambuddy
    ports:
      - "${PORT:-8000}:8000"           # Web UI
      - "990:990"                      # Proxy FTP control
      - "8883:8883"                    # Proxy MQTT
      - "50000-50100:50000-50100"      # Proxy FTP passive data
    volumes:
      - bambuddy_data:/app/data
      - bambuddy_logs:/app/logs
    environment:
      - TZ=Europe/Berlin
    restart: unless-stopped

volumes:
  bambuddy_data:
  bambuddy_logs:

docker-compose down && docker-compose up -d

# In your bambuddy.service file
AmbientCapabilities=CAP_NET_BIND_SERVICE

# UFW (Ubuntu/Debian)
sudo ufw allow 990/tcp comment "Bambuddy Proxy FTP"
sudo ufw allow 8883/tcp comment "Bambuddy Proxy MQTT"

# Or iptables
sudo iptables -A INPUT -p tcp --dport 990 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 8883 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 50000:50100 -j ACCEPT

# Make iptables rules persistent (Debian/Ubuntu)
sudo apt install iptables-persistent
sudo netfilter-persistent save

Step 2: Configure Remote Access (Router Port Forwarding)¶

To access from outside your home network, forward these ports on your router:

Step 3: Enable Proxy Mode in Bambuddy¶

1. Go to Settings → Virtual Printer
2. Select Proxy mode from the mode options
3. Select your Target Printer from the dropdown
4. Click the toggle to Enable Virtual Printer
5. Verify the status shows "Running" with the proxy ports

Step 5: Configure Your Slicer¶

In Bambu Studio or OrcaSlicer:

1. Go to Device → Add Printer → Add printer manually
2. Enter your Bambuddy server's external IP or hostname
3. Enter your printer's access code (not a Bambuddy password)
4. The printer should connect and show as online

Step 6: Print!¶

Select a model, slice it, and click Print. The job will be:

1. Sent to Bambuddy over the internet (encrypted)
2. Relayed to your printer on the local network (encrypted)
3. Started on your printer just like a local print

Proxy Mode Use Cases¶

Proxy Mode vs Other Modes¶

Proxy Mode Troubleshooting¶

Slicer can't connect:

• Verify port forwarding is configured correctly
• Check that Bambuddy's proxy is running (green status indicator)
• Ensure your firewall allows incoming connections on ports 990, 8883, and 50000-50100

Authentication fails:

• Use your printer's access code, not a Bambuddy password
• The access code is the same one you'd use for LAN mode printing

Connection drops during transfer:

• Large files may timeout on slow connections
• Check your internet upload speed

Printer shows offline in slicer:

• Verify the target printer is online in Bambuddy
• Check that the printer is in LAN mode
• Restart the proxy by toggling it off and on

Setup Required¶

The virtual printer uses privileged port 990 (FTPS) which requires special handling on most systems.

Required Ports¶

Certificate Installation¶

Step 1: Locate the CA Certificate¶

The Bambuddy CA certificate is at:

• Native install: data/virtual_printer/certs/bbl_ca.crt
• Docker: Extract with docker cp bambuddy:/app/data/virtual_printer/certs/bbl_ca.crt ./bambuddy-ca.crt

Step 2: Append the Bambuddy CA Certificate to Slicer¶

The slicer's printer.cer file contains PEM certificates. You need to append the Bambuddy CA certificate to this file.

Open printer.cer in a text editor and:

1. Go to the end of the file
2. Paste the entire contents of bambuddy-ca.crt after the last -----END CERTIFICATE-----
3. Save the file
4. Fully restart the slicer (Cmd+Q on macOS, not just close the window)

Certificate file locations:

Certificate Persistence¶

The CA certificate is generated once and persists across Bambuddy restarts. If you switch between Docker and native installations, share the certificate directory to avoid regenerating:

volumes:
  - ./virtual_printer/certs:/app/data/virtual_printer/certs

Multiple Bambuddy Hosts¶

Each Bambuddy installation generates its own unique CA certificate.

Option 1: Share the CA (Recommended)

Copy the certs/ directory from one host to all others:

# Copy certs from host1 to host2
scp -r host1:/path/to/data/virtual_printer/certs/ host2:/path/to/data/virtual_printer/

Then restart Bambuddy on host2. All hosts will use the same CA, so one certificate in the slicer works for all.

Option 2: Update Certificate When Switching Hosts

Each time you switch to a different Bambuddy host:

1. Extract the CA from the new host
2. Open the slicer's printer.cer file
3. Remove the old Bambuddy CA (if present) and append the new one
4. Fully restart the slicer

Platform Setup¶

Choose your platform below for specific setup instructions.

Linux (Native Installation)¶

Port 990 is a privileged port. You need iptables rules to redirect it:

# Redirect incoming traffic on port 990 to 9990
sudo iptables -t nat -A PREROUTING -p tcp --dport 990 -j REDIRECT --to-port 9990

# Redirect localhost traffic on port 990 to 9990
sudo iptables -t nat -A OUTPUT -o lo -p tcp --dport 990 -j REDIRECT --to-port 9990

Make rules persistent:

sudo apt install iptables-persistent
sudo netfilter-persistent save

sudo dnf install iptables-services
sudo service iptables save

sudo iptables-save > /etc/iptables/iptables.rules
sudo systemctl enable iptables

Firewall rules (if using UFW):

sudo ufw allow 2021/udp  # SSDP
sudo ufw allow 8883/tcp  # MQTT
sudo ufw allow 990/tcp   # FTPS
sudo ufw allow 9990/tcp  # FTPS internal
sudo ufw allow 50000:50100/tcp  # FTP passive data

Firewall rules (if using firewalld):

sudo firewall-cmd --permanent --add-port=2021/udp  # SSDP
sudo firewall-cmd --permanent --add-port=8883/tcp  # MQTT
sudo firewall-cmd --permanent --add-port=990/tcp   # FTPS
sudo firewall-cmd --permanent --add-port=9990/tcp  # FTPS internal
sudo firewall-cmd --permanent --add-port=50000-50100/tcp  # FTP passive data
sudo firewall-cmd --reload

Docker (Linux)¶

Docker requires host networking for SSDP discovery to work.

docker-compose.yml:

services:
  bambuddy:
    image: ghcr.io/maziggy/bambuddy:latest
    container_name: bambuddy
    network_mode: host  # Required for SSDP discovery
    volumes:
      - bambuddy_data:/app/data
      - bambuddy_logs:/app/logs
    environment:
      - TZ=Europe/Berlin
    restart: unless-stopped

volumes:
  bambuddy_data:
  bambuddy_logs:

You still need iptables rules on the host:

sudo iptables -t nat -A PREROUTING -p tcp --dport 990 -j REDIRECT --to-port 9990
sudo iptables -t nat -A OUTPUT -o lo -p tcp --dport 990 -j REDIRECT --to-port 9990

Make rules persistent (Debian/Ubuntu):

sudo apt install iptables-persistent
sudo netfilter-persistent save

Firewall rules (if using UFW):

sudo ufw allow 2021/udp  # SSDP
sudo ufw allow 8883/tcp  # MQTT
sudo ufw allow 990/tcp   # FTPS
sudo ufw allow 9990/tcp  # FTPS internal
sudo ufw allow 50000:50100/tcp  # FTP passive data

Firewall rules (if using firewalld):

sudo firewall-cmd --permanent --add-port=2021/udp  # SSDP
sudo firewall-cmd --permanent --add-port=8883/tcp  # MQTT
sudo firewall-cmd --permanent --add-port=990/tcp   # FTPS
sudo firewall-cmd --permanent --add-port=9990/tcp  # FTPS internal
sudo firewall-cmd --permanent --add-port=50000-50100/tcp  # FTP passive data
sudo firewall-cmd --reload

Docker (macOS / Windows)¶

1. Use bridge networking with port mapping
2. Add the printer manually in your slicer using the host IP address
3. Virtual printer discovery from slicers won't work

Unraid¶

1. Set Network Type to host in container settings

2. Add iptables rules via Unraid terminal:

   iptables -t nat -A PREROUTING -p tcp --dport 990 -j REDIRECT --to-port 9990
   iptables -t nat -A OUTPUT -o lo -p tcp --dport 990 -j REDIRECT --to-port 9990
   

3. Make rules persistent by adding to /boot/config/go:

   echo "iptables -t nat -A PREROUTING -p tcp --dport 990 -j REDIRECT --to-port 9990" >> /boot/config/go
   echo "iptables -t nat -A OUTPUT -o lo -p tcp --dport 990 -j REDIRECT --to-port 9990" >> /boot/config/go
   

Synology NAS¶

1. Use Host Network in Container Manager

2. SSH into your NAS and add iptables rules:

   sudo iptables -t nat -A PREROUTING -p tcp --dport 990 -j REDIRECT --to-port 9990
   

3. Create a scheduled task to restore rules on boot:

4. Control Panel → Task Scheduler → Create → Triggered Task → User-defined script
5. Event: Boot-up
6. Script: iptables -t nat -A PREROUTING -p tcp --dport 990 -j REDIRECT --to-port 9990

TrueNAS SCALE¶

1. Use Host Network when creating the app/container

2. Add iptables rules via shell:

   iptables -t nat -A PREROUTING -p tcp --dport 990 -j REDIRECT --to-port 9990
   iptables -t nat -A OUTPUT -o lo -p tcp --dport 990 -j REDIRECT --to-port 9990
   

Proxmox LXC¶

1. Enable nesting in container options (for iptables support)

2. Inside the LXC:

   apt install iptables
   iptables -t nat -A PREROUTING -p tcp --dport 990 -j REDIRECT --to-port 9990
   iptables -t nat -A OUTPUT -o lo -p tcp --dport 990 -j REDIRECT --to-port 9990
   
   # Make persistent
   apt install iptables-persistent
   netfilter-persistent save
   

Configuration¶

Enabling the Virtual Printer¶

1. Complete the platform setup above first
2. Go to Settings in Bambuddy
3. Scroll to the Virtual Printer section
4. Set an Access Code (exactly 8 characters)
5. Toggle Enable Virtual Printer to on
6. Choose your Archive Mode:
7. Immediate: Files are archived automatically when received
8. Queue for Review: Files go to pending uploads for manual review

Printer Model Selection¶

Choose which Bambu printer model the virtual printer should emulate:

Adding to Bambu Studio / Orca Slicer¶

Automatic Discovery¶

1. Ensure the virtual printer is enabled and running
2. In Bambu Studio/Orca Slicer, go to Device tab
3. Click Refresh or wait for discovery
4. The virtual printer "Bambuddy" should appear
5. Click to add it, entering the access code when prompted

Manual Addition¶

If automatic discovery doesn't work:

1. In Bambu Studio, go to Device → Add Printer
2. Select Add printer by IP
3. Enter the IP address of your Bambuddy server
4. Enter the access code
5. The printer will be added to your device list

Sending Prints to Bambuddy¶

How to Send a Print¶

1. Slice your model as usual
2. Select "Bambuddy" (or your virtual printer name) from the printer dropdown
3. Click the Send button (next to the Print button)
4. The file will be transferred to Bambuddy

What Happens Next¶

Depending on your Archive Mode setting:

• Immediate: The file is automatically archived
• Queue for Review: The file appears in Pending Uploads for you to review, assign to a project, add notes, or queue for printing

Troubleshooting¶

Printer Not Appearing in Slicer¶

1. Check virtual printer is enabled and showing "Running" status
2. Verify iptables rules are active:

   sudo iptables -t nat -L -n | grep 990
   

3. Check firewall - ports 2021/udp, 8883/tcp, 990/tcp, 50000-50100/tcp must be open
4. Same network - slicer and Bambuddy must be on the same subnet

FTP Error / Connection Reset¶

1. Verify iptables rules are correctly configured
2. Check permissions on the uploads directory
3. Check no other FTP server is using port 990
4. Review logs for specific error messages

"Wrong Printer Model" Error¶

The slicer's selected printer profile must match the virtual printer model in Bambuddy settings.

Permission Denied Errors¶

If you see "Permission denied" in the logs:

# Fix ownership of the virtual printer directory
sudo chown -R $(whoami):$(whoami) /path/to/bambuddy/data/virtual_printer

Authentication Failed¶

1. Verify access code matches in both Bambuddy and slicer
2. Access code must be exactly 8 characters
3. Try removing and re-adding the printer in your slicer

Wrong IP in SSDP / TLS Handshake Fails (Multi-NIC)¶

If Bambuddy has multiple network interfaces (LAN + VPN, Docker bridges, etc.), the auto-detected IP may be on the wrong interface:

1. Go to Settings → Virtual Printer
2. Enable the virtual printer if not already enabled
3. Under Network Interface Override, select the interface your slicer connects through
4. The virtual printer will restart with the correct IP in SSDP broadcasts and TLS certificate

TLS Connection Failed / Error -1¶

This typically means the slicer doesn't trust the virtual printer's certificate:

1. Verify Bambuddy CA is in slicer's certificate file:

   # Check that the Bambuddy CA appears in printer.cer
   grep -A1 "BEGIN CERTIFICATE" "/Applications/BambuStudio.app/Contents/Resources/cert/printer.cer" | tail -4
   

2. Wrong certificate? If you have multiple Bambuddy hosts or reinstalled, you must update the certificate. See Step 2.

3. Verify certificate fingerprints match:

   # On Bambuddy server (Docker)
   docker exec bambuddy openssl x509 -in /app/data/virtual_printer/certs/bbl_ca.crt -noout -fingerprint -sha1
   
   # On Bambuddy server (native)
   openssl x509 -in data/virtual_printer/certs/bbl_ca.crt -noout -fingerprint -sha1
   

   Verify this fingerprint appears in one of the certificates in your slicer's printer.cer.

4. Fully restart the slicer - Cmd+Q on macOS, or End Task on Windows. Just closing the window is not enough.

5. Regenerate certificates (last resort):

   # Delete certs and restart Bambuddy
   rm -rf /path/to/data/virtual_printer/certs/
   # Then disable and re-enable virtual printer in UI
   

   You'll need to remove the old Bambuddy CA from the slicer and append the new one.

Technical Details¶

Security¶

• MQTT control channel: Fully TLS-encrypted (slicer <-> Bambuddy <-> printer)
• FTP control channel: Fully TLS-encrypted (slicer <-> Bambuddy <-> printer)
• FTP data channel: Encrypted between Bambuddy and printer. Not encrypted between slicer and Bambuddy due to a Bambu Studio limitation. Use a VPN for end-to-end data encryption.
• Self-signed certificates are auto-generated
• Access code authentication required for all connections
• Certificates stored in data/virtual_printer/certs/

Limitations¶

• Only one virtual printer instance per Bambuddy installation
• SSDP discovery requires same LAN — use manual IP entry for VPN, remote, or Docker bridge setups
• Slicer must trust the self-signed certificate
• FTP data channel unencrypted on slicer side (use VPN for full encryption)