initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,89 @@
+# 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.