GoAdmio

pdf

Shrink PDF files in place with Ghostscript, for one domain, folder, file, or all of /home

On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also


Overview

/go/pdf finds PDF files and recompresses each one with Ghostscript. A file is replaced only if the compressed copy is smaller, so no PDF ever gets bigger. Each file keeps its original timestamps.

You can point it at:

You can also limit the run to files whose names start with certain letters, and choose a stronger, lower-quality compression with --screen.

[!WARNING] The original PDF is replaced, and no backup is kept. Compression reduces image quality and can invalidate digital signatures or remove some interactive features, such as form fields. Test on one file first, and make sure you have a backup.

The command needs Ghostscript (gs), which package installs. Run it as root: parts of it don't use sudo.


Quick start

# Compress every PDF in a domain's www folder
/go/pdf example.com

Syntax

/go/pdf <target> [prefix] [--screen]
/go/pdf <target> --md5 [--skip log] 
Form Behavior
/go/pdf <target> Compresses every PDF found at the target.
/go/pdf <target> <prefix> Compresses only PDFs whose file names start with prefix.
/go/pdf <target> --screen Uses the smaller, lower-quality screen setting.
/go/pdf <target> --md5 Starts 16 background runs, one for each starting character a to f and 0 to 9. See The --md5 option.

Every run is recorded in /var/log/go/pdf.log, with the time and the arguments you passed.


Options

Target

The first argument says where to look. The command uses the first rule that matches.

Target Meaning
An existing file or folder path That file, or every PDF inside that folder, including subfolders.
all Every PDF under /home, including mail folders and anything else stored there, not only www folders.
A domain name The PDFs in /home/<domain>/www.

If nothing matches, the command prints <target> does not exist and exits with status 1.

Other options

Option Required Default Notes
prefix No — The second argument. Only PDFs whose names start with it are processed, for example a matches a1.pdf. Case-sensitive. Ignored if it starts with --.
--screen No Off Uses Ghostscript's /screen setting (smallest files, lowest image quality) instead of /ebook.
--md5 No Off Splits the work into 16 background runs by first character of the file name. See The --md5 option.
--skip log No Off Used with --md5. Skips any starting character that already has a log file. Write it as two words.

Only files named *.pdf in lowercase are found. Files ending in .PDF are ignored.


Output

For each compressed PDF the command prints one line. The percentage is the new file's size compared with the original, so a lower number means more savings.

[1/12] Resizing /home/example.com/www/docs/a.pdf (42%)...
[2/12] Resizing /home/example.com/www/docs/b.pdf (Same Size)...
Message Meaning
Resizing <file> (<n>%)... The compressed copy was smaller and replaced the original.
Resizing <file> (Same Size)... The compressed copy was not smaller (the same size or larger), so the original was kept.
<target> does not exist The first argument matched nothing. Exit status 1.

When only one file is found, the [n/total] prefix is left out. If no PDFs are found, the command prints nothing.

Log

Each run appends one line to /var/log/go/pdf.log:

[Nov 21 12:00:00]# pdf example.com

With --md5, each background run also writes its own log, described below.


Examples

# Every PDF in a domain's www folder
/go/pdf example.com
# Only PDFs whose names start with "a"
/go/pdf example.com a
# Smaller files, lower quality
/go/pdf example.com --screen
# One folder
/go/pdf /home/example.com/www/uploads
# A single file
/go/pdf /home/example.com/www/uploads/report.pdf
# Every PDF on the server
/go/pdf all
# A large site, in 16 background runs
/go/pdf /home/example.com/www --md5
# Run the missing runs again, keeping those that already have a log
/go/pdf /home/example.com/www --md5 --skip log

Troubleshooting

An empty result is not an error: it means no matching PDFs were found.

Symptom Likely cause Fix
<target> does not exist The first argument isn't a file, folder, all, or a domain with a /home/<domain>/www folder. Check the spelling or pass a full path.
Nothing is printed No *.pdf files at the target, or none match the prefix. Check the folder. Files named .PDF are not found.
gs: command not found Ghostscript isn't installed. Run package, then try again.
A file is skipped or an error appears for a path with spaces File and folder names with spaces aren't handled. Rename the file, or process its parent folder after renaming.
Many files say (Same Size) They are already optimized, so the compressed copy was not smaller. None. The originals are untouched.
Compressed files are now owned by root, or can't be replaced over FTP The new file is created by the user running the command, normally root. Run fix for the account.
Quality is too low --screen was used, or the default is too strong for these files. Restore the originals from a backup with restore or snapshot.
The server is slow during --md5 Sixteen Ghostscript processes run at once. Wait, or run one character at a time, for example /go/pdf example.com a.
--md5 returned at once with status 1 Expected. See The --md5 option. Follow progress in the log files.

Details

The --md5 option

Despite its name, --md5 does not calculate any checksum. It is a way to split a big job across 16 background runs. This suits folders whose file names start with a hexadecimal character, such as files named by their MD5 hash.

/go/pdf <target> --md5

For each of the characters a b c d e f 0 1 2 3 4 5 6 7 8 9, the command starts a separate background run equivalent to /go/pdf <target> <character>, and then exits with status 1.

Behavior Detail
Log files Each run writes to /var/log/go/pdf/<domain>-<character>.log. The domain is read from the third part of the path, so use a full path such as /home/example.com/www.
Files processed Only PDFs whose names start with one of those 16 lowercase characters. Other names are not processed.
Skipping With --skip log, a character is skipped if its log file already exists. This lets you resume a run, but it also skips finished characters. Delete a log to process that character again.
Quality The background runs don't receive --screen, so they always use the default /ebook setting.
Progress Watch a run with tail -f /var/log/go/pdf/<domain>-<character>.log.

What happens to each file

Step Action
1 Ghostscript writes a compressed copy next to the original as <file>.bak, using /ebook (default) or /screen.
2 The original file's timestamps are copied onto the copy.
3 The sizes are compared.
4a If the copy is smaller, the original is deleted and the copy takes its name.
4b Otherwise, the copy is deleted and the original is left as it was.
Setting Ghostscript preset Image resolution Use
Default /ebook About 150 dpi A balance of size and quality.
--screen /screen About 72 dpi Smallest files, lowest quality.
flowchart TD
    A["pdf target [prefix]"] --> B{"Target found?"}
    B -- "No" --> X["Print does not exist, exit 1"]
    B -- "Yes" --> C{"--md5?"}
    C -- "Yes" --> D["Start 16 background runs, one per first character, exit 1"]
    C -- "No" --> E["Find the *.pdf files, filtered by prefix"]
    E --> F["For each file: Ghostscript writes file.bak"]
    F --> G{"Copy smaller?"}
    G -- "Yes" --> H["Replace the original"]
    G -- "No" --> I["Delete the copy, keep the original"]

See also

Command Description
img Shrink large images (over 512 KB) in place so they fit within 800×600 pixels
webp Convert images to WebP format
fix Reset ownership and permissions for one account or all accounts
package Upgrade system packages, then install any missing GoAdmio base packages and tools
snapshot Back up, list, check, restore, and delete restic snapshots of hosting accounts
restore Restore accounts, databases, SSL certificates, or folders from local or remote GoAdmio backups