mirror of
https://github.com/balena-io/balena-cli.git
synced 2024-12-22 06:57:48 +00:00
500 lines
16 KiB
TypeScript
500 lines
16 KiB
TypeScript
/**
|
||
* @license
|
||
* Copyright 2019 Balena Ltd.
|
||
*
|
||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||
* you may not use this file except in compliance with the License.
|
||
* You may obtain a copy of the License at
|
||
*
|
||
* http://www.apache.org/licenses/LICENSE-2.0
|
||
*
|
||
* Unless required by applicable law or agreed to in writing, software
|
||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
* See the License for the specific language governing permissions and
|
||
* limitations under the License.
|
||
*/
|
||
|
||
import { flags } from '@oclif/command';
|
||
import type * as BalenaSdk from 'balena-sdk';
|
||
import * as _ from 'lodash';
|
||
import * as path from 'path';
|
||
import Command from '../../command';
|
||
|
||
import { ExpectedError } from '../../errors';
|
||
import * as cf from '../../utils/common-flags';
|
||
import { getBalenaSdk, stripIndent, getCliForm } from '../../utils/lazy';
|
||
|
||
const BOOT_PARTITION = 1;
|
||
const CONNECTIONS_FOLDER = '/system-connections';
|
||
|
||
interface FlagsDef {
|
||
advanced?: boolean;
|
||
app?: string;
|
||
application?: string;
|
||
config?: string;
|
||
'config-app-update-poll-interval'?: number;
|
||
'config-network'?: string;
|
||
'config-wifi-key'?: string;
|
||
'config-wifi-ssid'?: string;
|
||
device?: string; // device UUID
|
||
'device-api-key'?: string;
|
||
'device-type'?: string;
|
||
help?: void;
|
||
version?: string;
|
||
'system-connection': string[];
|
||
'initial-device-name'?: string;
|
||
}
|
||
|
||
interface ArgsDef {
|
||
image: string;
|
||
}
|
||
|
||
interface Answers {
|
||
appUpdatePollInterval: number; // in minutes
|
||
deviceType: string; // e.g. "raspberrypi3"
|
||
network: 'ethernet' | 'wifi';
|
||
version: string; // e.g. "2.32.0+rev1"
|
||
wifiSsid?: string;
|
||
wifiKey?: string;
|
||
}
|
||
|
||
const deviceApiKeyDeprecationMsg = stripIndent`
|
||
The --device-api-key option is deprecated and will be removed in a future release.
|
||
A suitable key is automatically generated or fetched if this option is omitted.`;
|
||
|
||
export default class OsConfigureCmd extends Command {
|
||
public static description = stripIndent`
|
||
Configure a previously downloaded balenaOS image.
|
||
|
||
Configure a previously downloaded balenaOS image for a specific device type or
|
||
balena application.
|
||
|
||
Configuration settings such as WiFi authentication will be taken from the
|
||
following sources, in precedence order:
|
||
1. Command-line options like \`--config-wifi-ssid\`
|
||
2. A given \`config.json\` file specified with the \`--config\` option.
|
||
3. User input through interactive prompts (text menus).
|
||
|
||
The --device-type option may be used to override the application's default
|
||
device type, in case of an application with mixed device types.
|
||
|
||
The --system-connection (-c) option can be used to inject NetworkManager connection
|
||
profiles for additional network interfaces, such as cellular/GSM or additional
|
||
WiFi or ethernet connections. This option may be passed multiple times in case there
|
||
are multiple files to inject. See connection profile examples and reference at:
|
||
https://www.balena.io/docs/reference/OS/network/2.x/
|
||
https://developer.gnome.org/NetworkManager/stable/nm-settings.html
|
||
|
||
${deviceApiKeyDeprecationMsg.split('\n').join('\n\t\t')}
|
||
|
||
Note: This command is currently not supported on Windows natively. Windows users
|
||
are advised to install the Windows Subsystem for Linux (WSL) with Ubuntu, and use
|
||
the Linux release of the balena CLI:
|
||
https://docs.microsoft.com/en-us/windows/wsl/about
|
||
`;
|
||
public static examples = [
|
||
'$ balena os configure ../path/rpi3.img --device 7cf02a6',
|
||
'$ balena os configure ../path/rpi3.img --device 7cf02a6 --device-api-key <existingDeviceKey>',
|
||
'$ balena os configure ../path/rpi3.img --app MyApp',
|
||
'$ balena os configure ../path/rpi3.img --app MyApp --version 2.12.7',
|
||
'$ balena os configure ../path/rpi3.img --app MyFinApp --device-type raspberrypi3',
|
||
'$ balena os configure ../path/rpi3.img --app MyFinApp --device-type raspberrypi3 --config myWifiConfig.json',
|
||
];
|
||
|
||
public static args = [
|
||
{
|
||
name: 'image',
|
||
required: true,
|
||
description: 'path to a balenaOS image file, e.g. "rpi3.img"',
|
||
},
|
||
];
|
||
|
||
public static usage = 'os configure <image>';
|
||
|
||
public static flags: flags.Input<FlagsDef> = {
|
||
advanced: flags.boolean({
|
||
char: 'v',
|
||
description:
|
||
'ask advanced configuration questions (when in interactive mode)',
|
||
}),
|
||
app: flags.string({
|
||
description: "same as '--application'",
|
||
exclusive: ['application', 'device'],
|
||
}),
|
||
application: { exclusive: ['app', 'device'], ...cf.application },
|
||
config: flags.string({
|
||
description:
|
||
'path to a pre-generated config.json file to be injected in the OS image',
|
||
}),
|
||
'config-app-update-poll-interval': flags.integer({
|
||
description:
|
||
'interval (in minutes) for the on-device balena supervisor periodic app update check',
|
||
}),
|
||
'config-network': flags.string({
|
||
description: 'device network type (non-interactive configuration)',
|
||
options: ['ethernet', 'wifi'],
|
||
}),
|
||
'config-wifi-key': flags.string({
|
||
description: 'WiFi key (password) (non-interactive configuration)',
|
||
}),
|
||
'config-wifi-ssid': flags.string({
|
||
description: 'WiFi SSID (network name) (non-interactive configuration)',
|
||
}),
|
||
device: { exclusive: ['app', 'application'], ...cf.device },
|
||
'device-api-key': flags.string({
|
||
char: 'k',
|
||
description:
|
||
'custom device API key (DEPRECATED and only supported with balenaOS 2.0.3+)',
|
||
}),
|
||
'device-type': flags.string({
|
||
description:
|
||
'device type slug (e.g. "raspberrypi3") to override the application device type',
|
||
}),
|
||
'initial-device-name': flags.string({
|
||
description:
|
||
'This option will set the device name when the device provisions',
|
||
}),
|
||
help: cf.help,
|
||
version: flags.string({
|
||
description: 'balenaOS version, for example "2.32.0" or "2.44.0+rev1"',
|
||
}),
|
||
'system-connection': flags.string({
|
||
multiple: true,
|
||
char: 'c',
|
||
required: false,
|
||
description:
|
||
"paths to local files to place into the 'system-connections' directory",
|
||
}),
|
||
};
|
||
|
||
public async run() {
|
||
const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
|
||
OsConfigureCmd,
|
||
);
|
||
// Prefer options.application over options.app
|
||
options.application = options.application || options.app;
|
||
options.app = undefined;
|
||
|
||
await validateOptions(options);
|
||
|
||
const devInit = await import('balena-device-init');
|
||
const { promises: fs } = await import('fs');
|
||
const { generateDeviceConfig, generateApplicationConfig } = await import(
|
||
'../../utils/config'
|
||
);
|
||
const helpers = await import('../../utils/helpers');
|
||
let app: ApplicationWithDeviceType | undefined;
|
||
let device;
|
||
let deviceTypeSlug: string;
|
||
|
||
const balena = getBalenaSdk();
|
||
if (options.device) {
|
||
device = (await balena.models.device.get(options.device, {
|
||
$expand: {
|
||
is_of__device_type: { $select: 'slug' },
|
||
},
|
||
})) as DeviceWithDeviceType & {
|
||
belongs_to__application: BalenaSdk.PineDeferred;
|
||
};
|
||
deviceTypeSlug = device.is_of__device_type[0].slug;
|
||
} else {
|
||
app = (await balena.models.application.get(options.application!, {
|
||
$expand: {
|
||
is_for__device_type: { $select: 'slug' },
|
||
},
|
||
})) as ApplicationWithDeviceType;
|
||
await checkDeviceTypeCompatibility(balena, options, app);
|
||
deviceTypeSlug =
|
||
options['device-type'] || app.is_for__device_type[0].slug;
|
||
}
|
||
|
||
const deviceTypeManifest = await helpers.getManifest(
|
||
params.image,
|
||
deviceTypeSlug,
|
||
);
|
||
|
||
let configJson: import('../../utils/config').ImgConfig | undefined;
|
||
if (options.config) {
|
||
const rawConfig = await fs.readFile(options.config, 'utf8');
|
||
configJson = JSON.parse(rawConfig);
|
||
}
|
||
|
||
const answers: Answers = await askQuestionsForDeviceType(
|
||
deviceTypeManifest,
|
||
options,
|
||
configJson,
|
||
);
|
||
if (options.application) {
|
||
answers.deviceType = deviceTypeSlug;
|
||
}
|
||
answers.version =
|
||
options.version ||
|
||
(await getOsVersionFromImage(params.image, deviceTypeManifest, devInit));
|
||
|
||
if (_.isEmpty(configJson)) {
|
||
if (device) {
|
||
configJson = await generateDeviceConfig(
|
||
device,
|
||
options['device-api-key'],
|
||
answers,
|
||
);
|
||
} else {
|
||
configJson = await generateApplicationConfig(app!, answers);
|
||
}
|
||
}
|
||
|
||
if (
|
||
options['initial-device-name'] &&
|
||
options['initial-device-name'] !== ''
|
||
) {
|
||
configJson!.initialDeviceName = options['initial-device-name'];
|
||
}
|
||
|
||
console.info('Configuring operating system image');
|
||
|
||
const image = params.image;
|
||
await helpers.osProgressHandler(
|
||
await devInit.configure(
|
||
image,
|
||
deviceTypeManifest,
|
||
configJson || {},
|
||
answers,
|
||
),
|
||
);
|
||
|
||
if (options['system-connection']) {
|
||
const files = await Promise.all(
|
||
options['system-connection'].map(async (filePath) => {
|
||
const content = await fs.readFile(filePath, 'utf8');
|
||
const name = path.basename(filePath);
|
||
|
||
return {
|
||
name,
|
||
content,
|
||
};
|
||
}),
|
||
);
|
||
const imagefs = await import('resin-image-fs');
|
||
|
||
for (const { name, content } of files) {
|
||
await imagefs.writeFile(
|
||
{
|
||
image,
|
||
partition: BOOT_PARTITION,
|
||
path: path.join(CONNECTIONS_FOLDER, name),
|
||
},
|
||
content,
|
||
);
|
||
console.info(`Copied system-connection file: ${name}`);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
async function validateOptions(options: FlagsDef) {
|
||
if (process.platform === 'win32') {
|
||
throw new ExpectedError(stripIndent`
|
||
Unsupported platform error: the 'balena os configure' command currently requires
|
||
the Windows Subsystem for Linux in order to run on Windows. It was tested with
|
||
the Ubuntu 18.04 distribution from the Microsoft Store. With WSL, a balena CLI
|
||
release for Linux (rather than Windows) should be installed: for example, the
|
||
standalone zip package for Linux. (It is possible to have both a Windows CLI
|
||
release and a Linux CLI release installed simultaneously.) For more information
|
||
on WSL and the balena CLI installation options, please check:
|
||
- https://docs.microsoft.com/en-us/windows/wsl/about
|
||
- https://github.com/balena-io/balena-cli/blob/master/INSTALL.md
|
||
`);
|
||
}
|
||
// The 'device' and 'application' options are declared "exclusive" in the oclif
|
||
// flag definitions above, so oclif will enforce that they are not both used together.
|
||
if (!options.device && !options.application) {
|
||
throw new ExpectedError(
|
||
"Either the '--device' or the '--application' option must be provided",
|
||
);
|
||
}
|
||
if (!options.application && options['device-type']) {
|
||
throw new ExpectedError(
|
||
"The '--device-type' option can only be used in conjunction with the '--application' option",
|
||
);
|
||
}
|
||
if (options['device-api-key']) {
|
||
console.error(stripIndent`
|
||
-------------------------------------------------------------------------------------------
|
||
Warning: ${deviceApiKeyDeprecationMsg.split('\n').join('\n\t\t\t')}
|
||
-------------------------------------------------------------------------------------------
|
||
`);
|
||
}
|
||
|
||
await Command.checkLoggedIn();
|
||
}
|
||
|
||
/**
|
||
* Wrapper around balena-device-init.getImageOsVersion(). Throws ExpectedError
|
||
* if the OS image could not be read or the OS version could not be extracted
|
||
* from it.
|
||
* @param imagePath Local filesystem path to a balenaOS image file
|
||
* @param deviceTypeManifest Device type manifest object
|
||
*/
|
||
async function getOsVersionFromImage(
|
||
imagePath: string,
|
||
deviceTypeManifest: BalenaSdk.DeviceTypeJson.DeviceType,
|
||
devInit: typeof import('balena-device-init'),
|
||
): Promise<string> {
|
||
const osVersion = await devInit.getImageOsVersion(
|
||
imagePath,
|
||
deviceTypeManifest,
|
||
);
|
||
if (!osVersion) {
|
||
throw new ExpectedError(stripIndent`
|
||
Could not read OS version from the image. Please specify the balenaOS
|
||
version manually with the --version command-line option.`);
|
||
}
|
||
return osVersion;
|
||
}
|
||
|
||
/**
|
||
* Check that options['device-type'], e.g. 'raspberrypi3', is compatible with
|
||
* app.device_type, e.g. 'raspberry-pi2'. Throws ExpectedError if they are not
|
||
* compatible.
|
||
* @param sdk Balena Node SDK instance
|
||
* @param options oclif command-line options object
|
||
* @param app Balena SDK Application model object
|
||
*/
|
||
async function checkDeviceTypeCompatibility(
|
||
sdk: BalenaSdk.BalenaSDK,
|
||
options: FlagsDef,
|
||
app: ApplicationWithDeviceType,
|
||
) {
|
||
if (options['device-type']) {
|
||
const [appDeviceType, optionDeviceType] = await Promise.all([
|
||
sdk.models.device.getManifestBySlug(app.is_for__device_type[0].slug),
|
||
sdk.models.device.getManifestBySlug(options['device-type']),
|
||
]);
|
||
const helpers = await import('../../utils/helpers');
|
||
if (!helpers.areDeviceTypesCompatible(appDeviceType, optionDeviceType)) {
|
||
throw new ExpectedError(
|
||
`Device type ${options['device-type']} is incompatible with application ${options.application}`,
|
||
);
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Check if the given options or configJson objects (in this order) contain
|
||
* the answers to some configuration questions, and interactively ask the
|
||
* user the questions for which answers are missing. Questions such as:
|
||
*
|
||
* ? Network Connection (Use arrow keys)
|
||
* ethernet
|
||
* ❯ wifi
|
||
* ? Network Connection wifi
|
||
* ? Wifi SSID i-ssid
|
||
* ? Wifi Passphrase [input is hidden]
|
||
*
|
||
* The questions are extracted from the given deviceType "manifest".
|
||
*/
|
||
async function askQuestionsForDeviceType(
|
||
deviceType: BalenaSdk.DeviceTypeJson.DeviceType,
|
||
options: FlagsDef,
|
||
configJson?: import('../../utils/config').ImgConfig,
|
||
): Promise<Answers> {
|
||
const answerSources: any[] = [camelifyConfigOptions(options)];
|
||
const defaultAnswers: Partial<Answers> = {};
|
||
const questions: any = deviceType.options;
|
||
let extraOpts: { override: object } | undefined;
|
||
|
||
if (!_.isEmpty(configJson)) {
|
||
answerSources.push(configJson);
|
||
}
|
||
|
||
if (!options.advanced) {
|
||
const advancedGroup: any = _.find(questions, {
|
||
name: 'advanced',
|
||
isGroup: true,
|
||
});
|
||
if (!_.isEmpty(advancedGroup)) {
|
||
const helpers = await import('../../utils/helpers');
|
||
answerSources.push(helpers.getGroupDefaults(advancedGroup));
|
||
}
|
||
}
|
||
|
||
for (const questionName of getQuestionNames(deviceType)) {
|
||
for (const answerSource of answerSources) {
|
||
if (answerSource[questionName] != null) {
|
||
defaultAnswers[questionName] = answerSource[questionName];
|
||
break;
|
||
}
|
||
}
|
||
}
|
||
if (
|
||
!defaultAnswers.network &&
|
||
(defaultAnswers.wifiSsid || defaultAnswers.wifiKey)
|
||
) {
|
||
defaultAnswers.network = 'wifi';
|
||
}
|
||
|
||
if (!_.isEmpty(defaultAnswers)) {
|
||
extraOpts = { override: defaultAnswers };
|
||
}
|
||
|
||
return getCliForm().run(questions, extraOpts);
|
||
}
|
||
|
||
/**
|
||
* Given a deviceType "manifest" containing "options" properties, return an
|
||
* array of "question names" as in the following example.
|
||
*
|
||
* @param deviceType Device type "manifest", for example:
|
||
* { "slug": "raspberrypi3",
|
||
* "options": [{
|
||
* "options": [ {
|
||
* "name": "network",
|
||
* "choices": ["ethernet", "wifi"],
|
||
* ... }, {
|
||
* "name": "wifiSsid",
|
||
* "type": "text",
|
||
* ... }, {
|
||
* "options": [ {
|
||
* "name": "appUpdatePollInterval",
|
||
* "default": 10,
|
||
* ...
|
||
* @return Array of question names, for example:
|
||
* [ 'network', 'wifiSsid', 'wifiKey', 'appUpdatePollInterval' ]
|
||
*/
|
||
function getQuestionNames(
|
||
deviceType: BalenaSdk.DeviceTypeJson.DeviceType,
|
||
): Array<keyof Answers> {
|
||
const questionNames: string[] = _.chain(deviceType.options)
|
||
.flatMap(
|
||
(group: BalenaSdk.DeviceTypeJson.DeviceTypeOptions) =>
|
||
(group.isGroup && group.options) || [],
|
||
)
|
||
.map(
|
||
(groupOption: BalenaSdk.DeviceTypeJson.DeviceTypeOptionsGroup) =>
|
||
groupOption.name,
|
||
)
|
||
.filter()
|
||
.value();
|
||
return questionNames as Array<keyof Answers>;
|
||
}
|
||
|
||
/**
|
||
* Create and return a new object with the key-value pairs from the input object,
|
||
* renaming keys that start with the 'config-' prefix as follows:
|
||
* Sample input:
|
||
* { app: 'foo', 'config-wifi-key': 'mykey', 'config-wifi-ssid': 'myssid' }
|
||
* Output:
|
||
* { app: 'foo', wifiKey: 'mykey', wifiSsid: 'myssid' }
|
||
*/
|
||
function camelifyConfigOptions(options: FlagsDef): { [key: string]: any } {
|
||
return _.mapKeys(options, (_value, key) => {
|
||
if (key.startsWith('config-')) {
|
||
return key
|
||
.substring('config-'.length)
|
||
.replace(/-[a-z]/g, (match) => match.substring(1).toUpperCase());
|
||
}
|
||
return key;
|
||
});
|
||
}
|