# Paperless Scanner Integration (FTP)

Connect a network scanner (Brother MFC, etc.) to Paperless-ngx so scans land directly in the consume folder and are auto-ingested. Uses a lightweight FTP server (vsftpd) chrooted to the consume folder.

## Architecture

```
Brother MFC (192.168.50.219)
  → Scan-to-FTP profile
    → vsftpd on rayserver (192.168.50.98:21)
      → /mnt/seagate8tb/paperless/consume/
        → Paperless auto-ingests (OCR, classify, tag)
```

## Setup

### 1. Install vsftpd

```bash
sudo apt install -y vsftpd
```

### 2. Create restricted user

```bash
sudo useradd -m -d /mnt/seagate8tb/paperless/consume -s /usr/sbin/nologin paperscan
sudo chown paperscan:paperscan /mnt/seagate8tb/paperless/consume
echo "/usr/sbin/nologin" | sudo tee -a /etc/shells  # PAM needs valid shell
sudo passwd paperscan  # set to e.g. brotherscan123
```

### 3. vsftpd config (`/etc/vsftpd.conf`)

```
listen=YES
listen_ipv6=NO
anonymous_enable=NO
local_enable=YES
write_enable=YES
local_umask=022
chroot_local_user=YES
allow_writeable_chroot=YES
seccomp_sandbox=NO

# Passive mode — needed for Brother printers
pasv_enable=YES
pasv_min_port=40000
pasv_max_port=40005
pasv_address=192.168.50.98

# Restrict to paperscan user only
userlist_enable=YES
userlist_file=/etc/vsftpd.userlist
userlist_deny=NO
```

Create userlist: `echo "paperscan" | sudo tee /etc/vsftpd.userlist`

Start: `sudo systemctl enable --now vsftpd`

### 4. Verify

```bash
# Upload test file
echo "test" > /tmp/ftp_test.txt
curl -s -T /tmp/ftp_test.txt --user paperscan:brotherscan123 ftp://127.0.0.1/test.txt
ls -la /mnt/seagate8tb/paperless/consume/test.txt
rm /mnt/seagate8tb/paperless/consume/test.txt
```

### 5. Configure Brother printer

Open `http://192.168.50.219/` in a browser:
- **Scan** → **Scan to FTP/SFTP/Network** → **Create New Profile**
- Host: `192.168.50.98`, Port: `21`
- Username: `paperscan`, Password: `<password>`
- Store Directory: `/` (root)
- Quality: Color 300dpi, PDF

### Daily use

On the printer touchscreen: **Scan** → select profile → **Start**. The PDF appears in Paperless within seconds.

## Pitfalls

- **PAM rejects nologin shell**: vsftpd uses PAM, which checks `/etc/shells`. Add `/usr/sbin/nologin` to it.
- **Passive ports**: Brother printers need passive mode FTP. Set `pasv_enable=YES` and open ports 40000-40005 if using a firewall.
- **Chroot writable**: `allow_writeable_chroot=YES` is required when the chroot directory (consume) is writable by the FTP user.
- **Ownership**: Files uploaded via FTP are owned by the FTP user (`paperscan`). Paperless needs read access to the consume folder — `paperscan:paperscan` ownership works as long as Paperless runs as a user that can traverse the path. Verify with a test scan.