From 60d376c323d982c3a2e3c6c296271cc4900ba1eb Mon Sep 17 00:00:00 2001 From: albertony <12441419+albertony@users.noreply.github.com> Date: Tue, 26 Jan 2021 15:28:45 +0100 Subject: [PATCH] docs: add guide to configuring autorun in install documentation --- cmd/mountlib/mount.go | 8 +-- docs/content/install.md | 145 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 148 insertions(+), 5 deletions(-) diff --git a/cmd/mountlib/mount.go b/cmd/mountlib/mount.go index 83b0ea24c..724fea8e8 100644 --- a/cmd/mountlib/mount.go +++ b/cmd/mountlib/mount.go @@ -350,11 +350,9 @@ Command Prompt and then try to access the same drive from Explorer new drive. The easiest way around this is to start the drive from a normal -command prompt. It is also possible to start a drive from the SYSTEM -account (using [the WinFsp.Launcher -infrastructure](https://github.com/billziss-gh/winfsp/wiki/WinFsp-Service-Architecture)) -which creates drives accessible for everyone on the system or -alternatively using [the nssm service manager](https://nssm.cc/usage). +command prompt. It is also possible to start a drive as the SYSTEM +account, which creates drives accessible for everyone on the system, +read more in the [install documentation](https://rclone.org/install/). ### Limitations diff --git a/docs/content/install.md b/docs/content/install.md index 4d45bba54..3bb2ad936 100644 --- a/docs/content/install.md +++ b/docs/content/install.md @@ -12,6 +12,7 @@ Rclone is a Go program and comes as a single binary file. * [Download](/downloads/) the relevant binary. * Extract the `rclone` or `rclone.exe` binary from the archive * Run `rclone config` to setup. See [rclone config docs](/docs/) for more details. + * Optionally configure [automatic execution](#autostart). See below for some expanded Linux / macOS instructions. @@ -226,3 +227,147 @@ Instructions roles: - rclone ``` + +# Autostart # + +After installing and configuring rclone, as described above, you are ready to use rclone +as an interactive command line utility. If your goal is to perform *periodic* operations, +such as a regular [sync](https://rclone.org/commands/rclone_sync/), you will probably want +to configure your rclone command in your operating system's scheduler. If you need to +expose *service*-like features, such as [remote control](https://rclone.org/rc/), +[GUI](https://rclone.org/gui/), [serve](https://rclone.org/commands/rclone_serve/) +or [mount](https://rclone.org/commands/rclone_move/), you will often want an rclone +command always running in the background, and configuring it to run in a service infrastructure +may be a better option. Below are some alternatives on how to achieve this on +different operating systems. + +NOTE: Before setting up autorun it is highly recommended that you have tested your command +manually from a Command Prompt first. + +## Autostart on Windows ## + +The most relevant alternatives for autostart on Windows are: +- Run at user log on using the Startup folder +- Run at user log on, at system startup or at schedule using Task Scheduler +- Run at system startup using Windows service + +### Running in background + +Rclone is a console application, so if not starting from an existing Command Prompt, +e.g. when starting rclone.exe from a shortcut, it will open a Command Prompt window. +When configuring rclone to run from task scheduler and windows service you are able +to set it to run hidden in background. From rclone version 1.54 you can also make it +run hidden from anywhere by adding option `--no-console` (it may still flash briefly +when the program starts). Since rclone normally writes information and any error +messages to the console, you must redirect this to a file to be able to see it. +Rclone has a built-in option `--log-file` for that. + +Example command to run a sync in background: +``` +c:\rclone\rclone.exe sync c:\files remote:/files --no-console --log-file c:\rclone\logs\sync_files.txt +``` + +### User account + +As mentioned in the [mount](https://rclone.org/commands/rclone_move/) documentation, +mounted drives created as Administrator are not visible to other accounts, not even the +account that was elevated as Administrator. By running the mount command as the +built-in `SYSTEM` user account, it will create drives accessible for everyone on +the system. Both scheduled task and Windows service can be used to achieve this. + +NOTE: Remember that when rclone runs as the `SYSTEM` user, the user profile +that it sees will not be yours. This means that if you normally run rclone with +configuration file in the default location, to be able to use the same configuration +when running as the system user you must explicitely tell rclone where to find +it with the [`--config`](https://rclone.org/docs/#config-config-file) option, +or else it will look in the system users profile path (`C:\Windows\System32\config\systemprofile`). +To test your command manually from a Command Prompt, you can run it with +the [PsExec](https://docs.microsoft.com/en-us/sysinternals/downloads/psexec) +utility from Microsoft's Sysinternals suite, which takes option `-s` to +execute commands as the `SYSTEM` user. + +### Start from Startup folder ### + +To quickly execute an rclone command you can simply create a standard +Windows Explorer shortcut for the complete rclone command you want to run. If you +store this shortcut in the special "Startup" start-menu folder, Windows will +automatically run it at login. To open this folder in Windows Explorer, +enter path `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup`, +or `C:\ProgramData\Microsoft\Windows\Start Menu\Programs\StartUp` if you want +the command to start for *every* user that logs in. + +This is the easiest approach to autostarting of rclone, but it offers no +functionality to set it to run as different user, or to set conditions or +actions on certain events. Setting up a scheduled task as described below +will often give you better results. + +### Start from Task Scheduler ### + +Task Scheduler is an administrative tool built into Windows, and it can be used to +configure rclone to be started automatically in a highly configurable way, e.g. +periodically on a schedule, on user log on, or at system startup. It can run +be configured to run as the current user, or for a mount command that needs to +be available to all users it can run as the `SYSTEM` user. +For technical information, see +https://docs.microsoft.com/windows/win32/taskschd/task-scheduler-start-page. + +### Run as service ### + +For running rclone at system startup, you can create a Windows service that executes +your rclone command, as an alternative to scheduled task configured to run at startup. + +#### Mount command built-in service integration #### + +For mount commands, Rclone has a built-in Windows service integration via the third party +WinFsp library it uses. Registering as a regular Windows service easy, as you just have to +execute the built-in PowerShell command `New-Service` (requires administrative privileges). + +Example of a PowerShell command that creates a Windows service for mounting +some `remote:/files` as drive letter `X:`, for *all* users (service will be running as the +local system account): + +``` +New-Service -Name Rclone -BinaryPathName 'c:\rclone\rclone.exe mount remote:/files X: --config c:\rclone\config\rclone.conf --log-file c:\rclone\logs\mount.txt' +``` + +The [WinFsp service infrastructure](https://github.com/billziss-gh/winfsp/wiki/WinFsp-Service-Architecture) +supports incorporating services for file system implementations, such as rclone, +into its own launcher service, as kind of "child services". This has the additional +advantage that it also implements a network provider that integrates into +Windows standard methods for managing network drives. This is currently not +officially supported by Rclone, but with WinFsp version 2019.3 B2 / v1.5B2 or later +it should be possible through path rewriting as described [here](https://github.com/rclone/rclone/issues/3340). + +#### Third party service integration #### + +To Windows service running any rclone command, the excellent third party utility +[NSSM](http://nssm.cc), the "Non-Sucking Service Manager", can be used. +It includes some advanced features such as adjusting process periority, defining +process environment variables, redirect to file anything written to stdout, and +customized response to different exit codes, with a GUI to configure everything from +(although it can also be used from command line ). + +There are also several other alternatives. To mention one more, +[WinSW](https://github.com/winsw/winsw), "Windows Service Wrapper", is worth checking out. +It requires .NET Framework, but it is preinstalled on newer versions of Windows, and it +also provides alternative standalone distributions which includes necessary runtime (.NET 5). +WinSW is a command-line only utility, where you have to manually create an XML file with +service configuration. This may be a drawback for some, but it can also be an advantage +as it is easy to back up and re-use the configuration +settings, without having go through manual steps in a GUI. One thing to note is that +by default it does not restart the service on error, one have to explicit enable this +in the configuration file (via the "onfailure" parameter). + +## Autostart on Linux + +### Start as a service + +To always run rclone in background, relevant for mount commands etc, +you can use systemd to set up rclone as a system or user service. Running as a +system service ensures that it is run at startup even if the user it is running as +has no active session. Running rclone as a user service ensures that it only +starts after the configured user has logged into the system. + +### Run periodically from cron + +To run a periodic command, such as a copy/sync, you can set up a cron job.