diff --git a/docs/update-locking.md b/docs/update-locking.md index e9ecf4cb..407ea9a9 100644 --- a/docs/update-locking.md +++ b/docs/update-locking.md @@ -1,48 +1,47 @@ --- title: Application update locks -excerpt: Locking application updates on your resin.io devices +excerpt: Locking application updates on your balenaOS devices --- # Application update locks -Locking updates means that the resin.io device supervisor will not be able to kill your application. This is meant to be used at critical sections of your code where you don't want to be interrupted, or to ensure that updates are only installed at certain times. +Locking updates means that the balena supervisor will not be able to kill your application. This is meant to be used at critical sections of your code where you don't want to be interrupted, or to ensure that updates are only installed at certain times. -In order to do this, users can create a lockfile called `resin-updates.lock` in a way that it has exclusive access, which will prevent the device supervisor from killing and restarting the app. As with any other lockfile, the supervisor itself will create such a file before killing the app, so you should only create it in exclusive mode. This means that the lockfile should only be created if it doesn't already exist. The exclusive access is achieved by opening the lockfile with the [O_EXCL and O_CREAT flags](https://linux.die.net/man/3/open), and several tools exist to simplify this process with examples given [below](#creating-the-lockfile). +In order to do this, users can create a lockfile in a way that it has exclusive access, which will prevent the device supervisor from killing and restarting the app. As with any other lockfile, the supervisor itself will create such a file before killing the app, so you should only create it in exclusive mode. This means that the lockfile should only be created if it doesn't already exist. The exclusive access is achieved by opening the lockfile with the [O_EXCL and O_CREAT flags](https://linux.die.net/man/3/open), and several tools exist to simplify this process with examples given [below](#creating-the-lockfile). The presence of a lockfile will ensure that your application does not get killed, but updates will still be downloaded by the supervisor, ready to be applied once the lockfile no longer exists. ### Location of the lockfile -In supervisor v4.0.0 and higher, the lock is located at `/tmp/resin/resin-updates.lock`. This lock is cleared automatically when the device reboots, so the user app must take it every time it starts up. +On devices running supervisor 7.22.0 and higher, the lockfile is located at `/tmp/balena/updates.lock`. This lock is cleared automatically when the device reboots, so the user app must take it every time it starts up. -Older supervisors have the lock at `/data/resin-updates.lock`. This lock is still supported on devices running resinOS 1.X. In this case, newer supervisors will try to take *both* locks before killing the application. +On older devices (with v4.0.0 <= supervisor version < v7.22.0) the lock is located at `/tmp/resin/resin-updates.lock`. The latest supervisor versions still take the lock at this legacy path for backwards compatibility. -The old lock has the problem that the supervisor has to clear whenever it starts up to avoid deadlocks. If the user app +Legacy supervisors (< v4.0.0) have the lock at `/data/resin-updates.lock`. This lock is only supported on devices running resinOS 1.X. +This old lock has the problem that the supervisor has to clear whenever it starts up to avoid deadlocks. If the user app has taken the lock before the supervisor starts up, the lock will be cleared and the app can operate under the false assumption that updates are locked (see [issue #20](https://github.com/resin-io/resin-supervisor/issues/20)). We therefore strongly recommend switching to the new lock location as soon as possible. -For supervisors >= v4.0.0 and any OS that is not resinOS 1.x, the old lock location is completely ignored. - ### Creating the lockfile There are many different tools and libraries to provide proper lockfile functionality and a few common examples are shown below. -__Note:__ Just creating the lockfile, for example by using `touch /tmp/resin/resin-updates.lock`, is not adequate to prevent updates. A file created in this way won't have the exclusive access flag set, and thus does not provide reliable locking. +__Note:__ Just creating the lockfile, for example by using `touch /tmp/balena/updates.lock`, is not adequate to prevent updates. A file created in this way won't have the exclusive access flag set, and thus does not provide reliable locking. #### Shell One simple way to create a lockfile is using [lockfile](https://linux.die.net/man/1/lockfile) (available for example in Debian from the `procmail` package): ```shell -lockfile /tmp/resin/resin-updates.lock +lockfile /tmp/balena/updates.lock # ... (do things) -rm -f /tmp/resin/resin-updates.lock +rm -f /tmp/balena/updates.lock ``` Another tool is [flock](https://linux.die.net/man/1/flock) (available for example in Debian from the `linux-utils` package): ```shell -flock /tmp/resin/resin-updates.lock -c '... (command to run while locked)' +flock /tmp/balena/updates.lock -c '... (command to run while locked)' ``` For more examples and explanation of the functionality, check the links to the specific tools above. @@ -53,7 +52,7 @@ Using the [`lockfile` library](https://www.npmjs.com/package/lockfile), the lock ```coffeescript lockFile = require 'lockfile' -lockFile.lock '/tmp/resin/resin-updates.lock', (err) -> +lockFile.lock '/tmp/balena/updates.lock', (err) -> # A non-null err probably means the supervisor is about to kill us throw new Error('Could not acquire lock: ', err) if err? @@ -61,7 +60,7 @@ lockFile.lock '/tmp/resin/resin-updates.lock', (err) -> doTheHarlemShake() # Now we release the lock, and we can be killed again - lockFile.unlock '/tmp/resin/resin-updates.lock', (err) -> + lockFile.unlock '/tmp/balena/updates.lock', (err) -> # If err is not null here, something went really wrong throw err if err? ``` @@ -71,7 +70,7 @@ lockFile.lock '/tmp/resin/resin-updates.lock', (err) -> In Python you can use the [`lockfile` library](http://pythonhosted.org/lockfile/lockfile.html#examples) ```python from lockfile import LockFile -lock = LockFile("/tmp/resin/resin-updates.lock") +lock = LockFile("/tmp/balena/updates.lock") with lock: print lock.path, 'is locked.' ``` @@ -79,8 +78,8 @@ Check the link for more examples and other Python libraries that provide locking ### Overriding the lock -The update lock can be overriden in case you need to force an update, for instance, if your app has hung in a critical section. +The update lock can be overridden in case you need to force an update, for instance, if your app has hung in a critical section. The way to do this is hitting the `/v1/update` endpoint of the [supervisor HTTP API](./API.md), with `{ "force": true }` as body. -The lock can also be overriden by setting the app's `RESIN_SUPERVISOR_OVERRIDE_LOCK` configuration variable to "1". +The lock can also be overridden by setting the app's `BALENA_SUPERVISOR_OVERRIDE_LOCK` configuration variable to "1". diff --git a/entry.sh b/entry.sh index 7fc93a16..4c6cb22c 100755 --- a/entry.sh +++ b/entry.sh @@ -8,8 +8,15 @@ rm -f /var/run/avahi-daemon/pid /etc/init.d/dbus-1 start /etc/init.d/avahi-daemon start -[ -d /mnt/root/tmp/resin-supervisor ] || - mkdir -p /mnt/root/tmp/resin-supervisor +# If the legacy /tmp/resin-supervisor exists on the host, a container might +# already be using to take an update lock, so we symlink it to the new +# location so that the supervisor can see it +[ -d /mnt/root/tmp/resin-supervisor ] && + ( [ -d /mnt/root/tmp/balena-supervisor ] || ln ./resin-supervisor /mnt/root/tmp/balena-supervisor ) + +# Otherwise, if the lockfiles directory doesn't exist +[ -d /mnt/root/tmp/balena-supervisor ] || + mkdir -p /mnt/root/tmp/balena-supervisor # If DOCKER_ROOT isn't set then default it if [ -z "${DOCKER_ROOT}" ]; then diff --git a/src/compose/service.ts b/src/compose/service.ts index da050b4e..c591b8ed 100644 --- a/src/compose/service.ts +++ b/src/compose/service.ts @@ -699,20 +699,25 @@ export class Service { appId: number, serviceName: string, ): { [envVarName: string]: string } { - let env = _.defaults(environment, { - RESIN_APP_ID: appId.toString(), - RESIN_APP_NAME: options.appName, - RESIN_SERVICE_NAME: serviceName, - RESIN_DEVICE_UUID: options.uuid, - RESIN_DEVICE_TYPE: options.deviceType, - RESIN_HOST_OS_VERSION: options.osVersion, - RESIN_SUPERVISOR_VERSION: options.version, - RESIN_APP_LOCK_PATH: '/tmp/resin/resin-updates.lock', - RESIN_SERVICE_KILL_ME_PATH: '/tmp/resin/resin-kill-me', - RESIN: '1', - USER: 'root', - }); + let defaultEnv: { [ envVarName: string]: string } = {}; + for(let namespace of [ 'BALENA', 'RESIN' ]){ + _.assign(defaultEnv, _.mapKeys({ + APP_ID: appId.toString(), + APP_NAME: options.appName, + SERVICE_NAME: serviceName, + DEVICE_UUID: options.uuid, + DEVICE_TYPE: options.deviceType, + HOST_OS_VERSION: options.osVersion, + SUPERVISOR_VERSION: options.version, + APP_LOCK_PATH: '/tmp/balena/updates.lock', + }, (_val, key) => `${namespace}_${key}`)); + defaultEnv[namespace] = '1'; + } + defaultEnv['RESIN_SERVICE_KILL_ME_PATH'] = '/tmp/balena/handover-complete'; + defaultEnv['BALENA_SERVICE_HANDOVER_COMPLETE_PATH'] = '/tmp/balena/handover-complete'; + defaultEnv['USER'] = 'root'; + let env = _.defaults(environment, defaultEnv); const imageInfoEnv = _.get(options.imageInfo, 'Config.Env', []); env = _.defaults(env, conversions.envArrayToObject(imageInfoEnv)); return env; @@ -819,6 +824,7 @@ export class Service { private static defaultBinds(appId: number, serviceName: string): string[] { return [ `${updateLock.lockPath(appId, serviceName)}:/tmp/resin`, + `${updateLock.lockPath(appId, serviceName)}:/tmp/balena`, ]; } diff --git a/src/lib/update-lock.coffee b/src/lib/update-lock.coffee index e3fb28e7..f0f54608 100644 --- a/src/lib/update-lock.coffee +++ b/src/lib/update-lock.coffee @@ -11,13 +11,14 @@ constants = require './constants' { ENOENT } = require './errors' baseLockPath = (appId) -> - return path.join('/tmp/resin-supervisor/services', appId.toString()) + return path.join('/tmp/balena-supervisor/services', appId.toString()) exports.lockPath = (appId, serviceName) -> return path.join(baseLockPath(appId), serviceName) -lockFileOnHost = (appId, serviceName) -> - return path.join(constants.rootMountPoint, exports.lockPath(appId, serviceName), 'resin-updates.lock') +lockFilesOnHost = (appId, serviceName) -> + return _.map [ 'updates.lock', 'resin-updates.lock' ], (fileName) -> + path.join(constants.rootMountPoint, exports.lockPath(appId, serviceName), fileName) exports.UpdatesLockedError = class UpdatesLockedError extends TypedError locksTaken = {} @@ -46,14 +47,14 @@ exports.lock = do -> fs.readdirAsync(theLockDir) .catchReturn(ENOENT, []) .mapSeries (serviceName) -> - tmpLockName = lockFileOnHost(appId, serviceName) - Promise.try -> - lockFile.unlockAsync(tmpLockName) if force == true - .then -> - lockFile.lockAsync(tmpLockName) - .then -> - locksTaken[tmpLockName] = true - .catchReturn(ENOENT, null) + Promise.mapSeries lockFilesOnHost(appId, serviceName), (tmpLockName) -> + Promise.try -> + lockFile.unlockAsync(tmpLockName) if force == true + .then -> + lockFile.lockAsync(tmpLockName) + .then -> + locksTaken[tmpLockName] = true + .catchReturn(ENOENT, null) .catch (err) -> dispose(release) .throw(new exports.UpdatesLockedError("Updates are locked: #{err.message}")) diff --git a/test/04-service.spec.coffee b/test/04-service.spec.coffee index 0350839e..cf3e54bf 100644 --- a/test/04-service.spec.coffee +++ b/test/04-service.spec.coffee @@ -18,7 +18,7 @@ configs = { } } -describe 'compose/service.coffee', -> +describe 'compose/service', -> it 'extends environment variables properly', -> extendEnvVarsOpts = { @@ -52,9 +52,19 @@ describe 'compose/service.coffee', -> RESIN_HOST_OS_VERSION: 'Resin OS 2.0.2' RESIN_SERVICE_NAME: 'serviceName' RESIN_SUPERVISOR_VERSION: 'v1.0.0' - RESIN_APP_LOCK_PATH: '/tmp/resin/resin-updates.lock' - RESIN_SERVICE_KILL_ME_PATH: '/tmp/resin/resin-kill-me' + RESIN_APP_LOCK_PATH: '/tmp/balena/updates.lock' + RESIN_SERVICE_KILL_ME_PATH: '/tmp/balena/handover-complete' RESIN: '1' + BALENA_APP_ID: '23' + BALENA_APP_NAME: 'awesomeApp' + BALENA_DEVICE_UUID: '1234' + BALENA_DEVICE_TYPE: 'raspberry-pi' + BALENA_HOST_OS_VERSION: 'Resin OS 2.0.2' + BALENA_SERVICE_NAME: 'serviceName' + BALENA_SUPERVISOR_VERSION: 'v1.0.0' + BALENA_APP_LOCK_PATH: '/tmp/balena/updates.lock' + BALENA_SERVICE_HANDOVER_COMPLETE_PATH: '/tmp/balena/handover-complete' + BALENA: '1' USER: 'root' }) @@ -68,7 +78,8 @@ describe 'compose/service.coffee', -> }, { appName: 'foo' }) binds = Service.defaultBinds(s.appId, s.serviceName) expect(binds).to.deep.equal([ - '/tmp/resin-supervisor/services/1234/foo:/tmp/resin' + '/tmp/balena-supervisor/services/1234/foo:/tmp/resin' + '/tmp/balena-supervisor/services/1234/foo:/tmp/balena' ]) it 'produces the correct port bindings and exposed ports', -> diff --git a/test/data/docker-states/entrypoint/inspect.json b/test/data/docker-states/entrypoint/inspect.json index bef65e8f..a96f7397 100644 --- a/test/data/docker-states/entrypoint/inspect.json +++ b/test/data/docker-states/entrypoint/inspect.json @@ -34,7 +34,8 @@ "ExecIDs": null, "HostConfig": { "Binds": [ - "/tmp/resin-supervisor/services/1011165/main:/tmp/resin" + "/tmp/balena-supervisor/services/1011165/main:/tmp/resin", + "/tmp/balena-supervisor/services/1011165/main:/tmp/balena" ], "ContainerIDFile": "", "LogConfig": { @@ -114,11 +115,19 @@ "Mounts": [ { "Type": "bind", - "Source": "/tmp/resin-supervisor/services/1011165/main", + "Source": "/tmp/balena-supervisor/services/1011165/main", "Destination": "/tmp/resin", "Mode": "", "RW": true, "Propagation": "rprivate" + }, + { + "Type": "bind", + "Source": "/tmp/balena-supervisor/services/1011165/main", + "Destination": "/tmp/balena", + "Mode": "", + "RW": true, + "Propagation": "rprivate" } ], "Config": { @@ -139,9 +148,19 @@ "RESIN_DEVICE_TYPE=raspberrypi3", "RESIN_HOST_OS_VERSION=Resin OS 2.13.6+rev1", "RESIN_SUPERVISOR_VERSION=7.18.0", - "RESIN_APP_LOCK_PATH=/tmp/resin/resin-updates.lock", - "RESIN_SERVICE_KILL_ME_PATH=/tmp/resin/resin-kill-me", + "RESIN_APP_LOCK_PATH=/tmp/balena/updates.lock", + "RESIN_SERVICE_KILL_ME_PATH=/tmp/balena/handover-complete", "RESIN=1", + "BALENA_APP_ID=1011165", + "BALENA_APP_NAME=supervisortest", + "BALENA_SERVICE_NAME=main", + "BALENA_DEVICE_UUID=a7feb967fac7f559ccf2a006a36bcf5d", + "BALENA_DEVICE_TYPE=raspberrypi3", + "BALENA_HOST_OS_VERSION=Resin OS 2.13.6+rev1", + "BALENA_SUPERVISOR_VERSION=7.18.0", + "BALENA_APP_LOCK_PATH=/tmp/balena/updates.lock", + "BALENA_SERVICE_HANDOVER_COMPLETE_PATH=/tmp/balena/handover-complete", + "BALENA=1", "USER=root", "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], @@ -207,4 +226,4 @@ } } } -} \ No newline at end of file +} diff --git a/test/data/docker-states/simple/inspect.json b/test/data/docker-states/simple/inspect.json index 17771b71..cde71139 100644 --- a/test/data/docker-states/simple/inspect.json +++ b/test/data/docker-states/simple/inspect.json @@ -35,7 +35,8 @@ "ExecIDs": null, "HostConfig": { "Binds": [ - "/tmp/resin-supervisor/services/1011165/main:/tmp/resin" + "/tmp/balena-supervisor/services/1011165/main:/tmp/resin", + "/tmp/balena-supervisor/services/1011165/main:/tmp/balena" ], "ContainerIDFile": "", "LogConfig": { @@ -114,11 +115,19 @@ "Mounts": [ { "Type": "bind", - "Source": "/tmp/resin-supervisor/services/1011165/main", + "Source": "/tmp/balena-supervisor/services/1011165/main", "Destination": "/tmp/resin", "Mode": "", "RW": true, "Propagation": "rprivate" + }, + { + "Type": "bind", + "Source": "/tmp/balena-supervisor/services/1011165/main", + "Destination": "/tmp/balena", + "Mode": "", + "RW": true, + "Propagation": "rprivate" } ], "Config": { @@ -139,9 +148,19 @@ "RESIN_DEVICE_TYPE=raspberrypi3", "RESIN_HOST_OS_VERSION=Resin OS 2.13.6+rev1", "RESIN_SUPERVISOR_VERSION=7.16.6", - "RESIN_APP_LOCK_PATH=/tmp/resin/resin-updates.lock", - "RESIN_SERVICE_KILL_ME_PATH=/tmp/resin/resin-kill-me", + "RESIN_APP_LOCK_PATH=/tmp/balena/updates.lock", + "RESIN_SERVICE_KILL_ME_PATH=/tmp/balena/handover-complete", "RESIN=1", + "BALENA_APP_ID=1011165", + "BALENA_APP_NAME=supervisortest", + "BALENA_SERVICE_NAME=main", + "BALENA_DEVICE_UUID=7dadabd4edec3067948d5952c2f2f26f", + "BALENA_DEVICE_TYPE=raspberrypi3", + "BALENA_HOST_OS_VERSION=Resin OS 2.13.6+rev1", + "BALENA_SUPERVISOR_VERSION=7.16.6", + "BALENA_APP_LOCK_PATH=/tmp/balena/updates.lock", + "BALENA_SERVICE_HANDOVER_COMPLETE_PATH=/tmp/balena/handover-complete", + "BALENA=1", "USER=root", "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", "UDEV=on" @@ -224,4 +243,4 @@ } } } -} \ No newline at end of file +} diff --git a/test/lib/application-manager-test-states.coffee b/test/lib/application-manager-test-states.coffee index 3f2365c5..3b5ceaf8 100644 --- a/test/lib/application-manager-test-states.coffee +++ b/test/lib/application-manager-test-states.coffee @@ -336,7 +336,8 @@ currentState[0] = { privileged: false restart: 'always' volumes: [ - '/tmp/resin-supervisor/services/1234/aservice:/tmp/resin' + '/tmp/balena-supervisor/services/1234/aservice:/tmp/resin', + '/tmp/balena-supervisor/services/1234/aservice:/tmp/balena' ] labels: { 'io.resin.app-id': '1234' @@ -365,7 +366,8 @@ currentState[0] = { 'ADDITIONAL_ENV_VAR': 'foo' } volumes: [ - '/tmp/resin-supervisor/services/1234/anotherService:/tmp/resin' + '/tmp/balena-supervisor/services/1234/anotherService:/tmp/resin', + '/tmp/balena-supervisor/services/1234/anotherService:/tmp/balena' ] privileged: false restart: 'always' @@ -445,7 +447,8 @@ currentState[2] = { privileged: false restart: 'always' volumes: [ - '/tmp/resin-supervisor/services/1234/aservice:/tmp/resin' + '/tmp/balena-supervisor/services/1234/aservice:/tmp/resin', + '/tmp/balena-supervisor/services/1234/aservice:/tmp/balena' ] labels: { 'io.resin.app-id': '1234' @@ -501,7 +504,8 @@ currentState[3] = { privileged: false restart: 'always' volumes: [ - '/tmp/resin-supervisor/services/1234/aservice:/tmp/resin' + '/tmp/balena-supervisor/services/1234/aservice:/tmp/resin', + '/tmp/balena-supervisor/services/1234/aservice:/tmp/balena' ] labels: { 'io.resin.app-id': '1234' @@ -534,7 +538,8 @@ currentState[3] = { privileged: false restart: 'always' volumes: [ - '/tmp/resin-supervisor/services/1234/aservice:/tmp/resin' + '/tmp/balena-supervisor/services/1234/aservice:/tmp/resin', + '/tmp/balena-supervisor/services/1234/aservice:/tmp/balena' ] labels: { 'io.resin.app-id': '1234' @@ -586,7 +591,8 @@ currentState[4] = { 'ADDITIONAL_ENV_VAR': 'foo' } volumes: [ - '/tmp/resin-supervisor/services/1234/anotherService:/tmp/resin' + '/tmp/balena-supervisor/services/1234/anotherService:/tmp/resin', + '/tmp/balena-supervisor/services/1234/anotherService:/tmp/balena' ] privileged: false restart: 'always'