PlexBackup.ps1

PlexBackup.ps1 is a PowerShell script that can back up and restore Plex application data files on a Windows system. This document explains how it works and how to use it. If you don't care about the details and just want to get the instruction, see Getting Started.

Introduction

Plex does not offer a meaningful backup feature. Yes, it can back up a Plex database which can be handy in case of a Plex database corruption, but if you need to move your Plex instance to a different system or restore it after a hard drive crash, a single database backup will be of little use. For a meaningful backup, in addition to the Plex database, you will need a copy of the Plex Windows registry key and tens (or hundreds) of thousands of Plex application data files. Keep in mind that backing up gigabytes of data files may take a long time, especially when they are copied remotely, such as to a NAS share. And you must keep the Plex Media Server stopped while the backup job is running (otherwise, it can corrupt the data). In the other words, a meaningful Plex backup is a challenge to which I could not find a good solution, so I decided to build my own. Ladies and gentlemen, meet PlexBackup.ps1.

Overview

PlexBackup.ps1 (or, briefly, PlexBackup) is a PowerShell script that can back up and restore a Plex instance on a Windows system. The script backs up the Plex database, Windows registry key, and app data folders essential for the Plex operations (it ignores the non-essential files, such as logs or crash reports). And it makes sure that Plex is not running when the backup job is active (which may take hours). And it can send email to you, too.

IMPORTANT: The script will not back up media (video, audio, images) or Plex program files. You must use different backup techniques for those. For example, you can keep your media files on a RAID 5 disk array (for redundancy) and back them up to an alternative storage on a periodic basis. And you don't really need to back up Plex program files, since you can always download them. But for everything else, PlexBackup is your guy.

Backup types

The script can perform two types of backup: compressed (default or 7zip) and uncompressed (Robocopy).

Default

By default, the script compresses every essential folder under the root of the Plex application data folder (Plex Media Server) and saves the compressed data as separate ZIP files. For better efficiency (in case the backup folder is remote, such as on a NAS share), it first compresses the data in a temporary local file and then moves the compressed file to a backup folder (you can compress the data and save the ZIP files directly to the backup folder by setting the value of the TempDir parameter to null or empty string). There is a problem with PowerShell's compression routine that fails to process files and folders with paths that are longer than 260 characters. If you get this error, use the SpecialDirs parameter (in code or config file) to specify the folders that are too long (or parents of the subfolders or files that are too long) and PlexBackup will copy them as-is without using compression (by default, the following application data folder is not compressed: Plug-in Support\Data\com.plexapp.system\DataItems\Deactivated).

7zip

Instead of the default compression, you can use the 7-zip command-line tool (7z.exe). 7-zip works faster (for both compression and extraction), it produces smaller compressed files, and it allowes you to exclude specific file types using the ExcludeFiles parameter (by default, it excludes *.bif, i.e. thumbnail preview files). To use 7-zip compression, install 7-zip, and set the PlexBackup script's Type parameter to 7zip (i.e. -Type 7zip) or use the -SevenZip shortcut (on command line). If you install 7-zip in a non-default directory, use the ArchiverPath parameter to set path to the 7z.exe file.

Robocopy

If you run PlexBackup with the Robocopy switch, instead of compression, the script will create a mirror of the Plex application data folder (minus the non-essential folders) using the Robocopy command (executed with the /MIR switch). Robocopy also allows you to exclude specific file types as described above.

You may want to play with either option to see which one works better for you.

Backup modes

PlexBackup can run in the following modes (specified by the Mode switch or a corresponding shortcut):

Backup: the default mode that creates a new backup archive.
Continue: resumes an incomplete backup job or, in case of the Robocopy backup, re-syncs the backup archive.
Restore: restores Plex application data from a backup.

If a previous backup does not exist, the Continue mode will behave just like the Backup mode. When running in the Continue mode for backup jobs that use compression, the script will skip the folders that already have the corresponding archive files. For the Robocopy backup, the Continue mode will synchronize the existing backup archive with the Plex application data files.

In all cases, before performing a backup or restore operation, PlexBackup will stop all Plex Windows services along with the Plex Media Server process. After the script completes the operation, it will restart them. You can use the NoRestart switch to tell the script not to restart the Plex Media Server process. The script will not run if the Plex Media Server is not active. To execute the script when Plex Media Server is not running, use the Inactive switch, but make sure you know what you are doing.

Plex Windows Registry key

To make sure PlexBackup saves and restores the right registry key, run it under the same account as Plex Media Server runs. The registry key will be backed up every time a backup job runs. If the backup folder does not contain the backup registry key file, the Plex registry key will not be imported on a restore.

Script execution

You must launch PlexBackup as Administrator while being logged in under the same account your Plex Media Server runs.

If you haven't done this already, you may need to adjust the PowerShell script execution policy to allow scripts to run. To check the current execution policy, run the following command from the PowerShell prompt:

Get-ExecutionPolicy

If the execution policy does not allow running scripts, do the following:

Start Windows PowerShell with the "Run as Administrator" option.
Run the following command:

Set-ExecutionPolicy RemoteSigned

This will allow running unsigned scripts that you write on your local computer and signed scripts downloaded from the Internet (okay, this is not a signed script, but if you copy it locally, make a non-destructive change--e.g. add a space character, remove the space character, and save the file--it should work).

Alternatively, you may want to run the script as:

start powershell.exe -noprofile -executionpolicy bypass -file .\PlexBackup.ps1 -ConfigFile .\PlexBackup.ps1.json

For additional information, see Running Scripts at Microsoft TechNet Library.

Dependencies

PlexBackup uses the following modules:

To verify that the modules get installed, run the script manually. You may be prompted to update the NuGet version (or you can do it yourself in advance).

Runtime parameters

The default values of the PlexBackup script's runtime parameters are defined in code, but you can override some of them via command-line arguments or config file settings.

Config file

Config file is optional. The default config file must be named after the PlexBackup script with the .json extension, such as PlexBackup.ps1.json. If the file with this name does not exist in the backup script's folder, PlexBackup will not care. You can also specify a custom config file name (or more accurately, path) via the ConfigFile command-line argument (see sample).

A config file must use JSON formatting, such as:

{
    "_meta": {
        "version": "1.0",
        "strict": false,
        "description": "Sample run-time settings for the PlexBackup.ps1 script."
    },
    "Mode": {
        "_meta": {
            "set": "Backup,Continue,Restore",
            "default": "Backup"
        },
        "value": null
    },
    "Type": {
        "_meta": {
            "set": ",7zip,Robocopy",
            "default": ""
        },
        "value": null
    },
    "PlexAppDataDir": {
        "_meta": {
            "default": "$env:LOCALAPPDATA\\Plex Media Server"
        },
        "value": null
    },
    "BackupRootDir": {
        "_meta": {
            "default": "$PSScriptRoot"
        },
        "value": null
    },
    "BackupDir": {
        "_meta": {
            "default": null
        },
        "value": null
    },
    "TempDir": {
        "_meta": {
            "default": "$env:TEMP"
        },
        "hasValue": true,
        "value": null
    },
    "WakeUpDir

PlexBackup

Install / Use

README