mirror of
https://github.com/balena-io/balena-cli.git
synced 2024-12-22 15:02:22 +00:00
6ba67eefdb
Change-Type: minor Signed-off-by: Nitish Agarwal 1592163+nitishagar@users.noreply.github.com
527 lines
16 KiB
TypeScript
527 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 { promisify } from 'util';
|
||
import * as _ from 'lodash';
|
||
import Command from '../../command';
|
||
import { ExpectedError } from '../../errors';
|
||
import * as cf from '../../utils/common-flags';
|
||
import { getBalenaSdk, stripIndent, getCliForm } from '../../utils/lazy';
|
||
import {
|
||
applicationIdInfo,
|
||
appToFleetFlagMsg,
|
||
warnify,
|
||
} from '../../utils/messages';
|
||
import { isV13 } from '../../utils/version';
|
||
|
||
const CONNECTIONS_FOLDER = '/system-connections';
|
||
|
||
interface FlagsDef {
|
||
advanced?: boolean;
|
||
application?: string;
|
||
app?: string;
|
||
fleet?: 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;
|
||
'provisioning-key-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;
|
||
provisioningKeyName?: 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 fleet.
|
||
|
||
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 fleet's default device
|
||
type, in case of a fleet 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/ref-settings.html
|
||
|
||
${deviceApiKeyDeprecationMsg.split('\n').join('\n\t\t')}
|
||
|
||
${applicationIdInfo.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 --fleet myorg/myfleet',
|
||
'$ balena os configure ../path/rpi3.img --fleet MyFleet --version 2.12.7',
|
||
'$ balena os configure ../path/rpi3.img -f MyFinFleet --device-type raspberrypi3',
|
||
'$ balena os configure ../path/rpi3.img -f MyFinFleet --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)',
|
||
}),
|
||
...(isV13()
|
||
? {}
|
||
: {
|
||
application: {
|
||
...cf.application,
|
||
exclusive: ['app', 'fleet', 'device'],
|
||
},
|
||
app: {
|
||
...cf.app,
|
||
exclusive: ['application', 'fleet', 'device'],
|
||
},
|
||
}),
|
||
fleet: {
|
||
...cf.fleet,
|
||
exclusive: ['app', 'application', 'device'],
|
||
},
|
||
config: flags.string({
|
||
description:
|
||
'path to a pre-generated config.json file to be injected in the OS image',
|
||
exclusive: ['provisioning-key-name'],
|
||
}),
|
||
'config-app-update-poll-interval': flags.integer({
|
||
description:
|
||
'supervisor cloud polling interval in minutes (e.g. for variable updates)',
|
||
}),
|
||
'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', 'fleet', 'provisioning-key-name'],
|
||
...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 fleet device type',
|
||
}),
|
||
'initial-device-name': flags.string({
|
||
description:
|
||
'This option will set the device name when the device provisions',
|
||
}),
|
||
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",
|
||
}),
|
||
'provisioning-key-name': flags.string({
|
||
description: 'custom key name assigned to generated provisioning api key',
|
||
exclusive: ['config', 'device'],
|
||
}),
|
||
help: cf.help,
|
||
};
|
||
|
||
public static authenticated = true;
|
||
|
||
public async run() {
|
||
const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
|
||
OsConfigureCmd,
|
||
);
|
||
if ((options.application || options.app) && process.stderr.isTTY) {
|
||
console.error(warnify(appToFleetFlagMsg));
|
||
}
|
||
options.application ||= options.app || options.fleet;
|
||
|
||
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');
|
||
const { getApplication } = await import('../../utils/sdk');
|
||
|
||
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 getApplication(balena, 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));
|
||
|
||
answers.provisioningKeyName = options['provisioning-key-name'];
|
||
|
||
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 path = await import('path');
|
||
|
||
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 { getBootPartition } = await import('balena-config-json');
|
||
const bootPartition = await getBootPartition(params.image);
|
||
|
||
const imagefs = await import('balena-image-fs');
|
||
|
||
for (const { name, content } of files) {
|
||
await imagefs.interact(image, bootPartition, async (_fs) => {
|
||
return await promisify(_fs.writeFile)(
|
||
path.join(CONNECTIONS_FOLDER, name),
|
||
content,
|
||
);
|
||
});
|
||
console.info(`Copied system-connection file: ${name}`);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
async function validateOptions(options: FlagsDef) {
|
||
// 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 '--fleet' 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 '--fleet' 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 fleet ${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;
|
||
});
|
||
}
|