### Install and Activate PI-Only Update with Old Boot Image (SmartOS)

Source: https://github.com/tritondatacenter/smartos-live/blob/master/man/usr/share/man/man8/piadm.8.md

This example illustrates how to install a platform image (PI) from a URL, even if it doesn't have a matching boot image, and then activate it. It shows the initial PI list, the installation process, and the final state after activation, highlighting the use of an older boot image.

```shell
[root@smartos ~]# piadm list
 PI STAMP           BOOTABLE FILESYSTEM            BOOT IMAGE   NOW   NEXT
 20200714T195617Z   standalone/boot                next         yes   yes
 [root@smartos ~]# piadm -v install https://example.com/PIs/platform-20200715T192200Z.tgz
 Installing https://example.com/PIs/platform-20200715T192200Z.tgz
         (downloaded to /tmp/tmp.Bba0Ac)
 Installing PI 20200715T192200Z
 [root@smartos ~]# piadm list
 PI STAMP           BOOTABLE FILESYSTEM            BOOT IMAGE   NOW   NEXT
 20200714T195617Z   standalone/boot                next         yes   yes
 20200715T192200Z   standalone/boot                none         no    no
 [root@smartos ~]# piadm -v activate 20200715T192200Z
 Platform Image 20200715T192200Z will be loaded on next boot,
     WARNING:  20200715T192200Z has no matching boot image, using
     boot image  20200714T195617Z
 [root@smartos ~]# piadm list
 PI STAMP           BOOTABLE FILESYSTEM            BOOT IMAGE   NOW   NEXT
 20200714T195617Z   standalone/boot                next         yes   no
 20200715T192200Z   standalone/boot                none         no    yes
 [root@smartos ~]#
```

--------------------------------

### Install Nodeunit

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/README.md

Provides instructions for installing the Nodeunit framework via command line tools.

```bash
# Option 1: Build from source
make && sudo make install

# Option 2: Install via npm
npm install nodeunit -g
```

--------------------------------

### Nodeunit Vim Integration Example

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/README.md

Example command for using Nodeunit with Vim, likely through a plugin like nodeunit.vim. This setup leverages the 'machineout' reporter for easier integration with tools like vim-makegreen.

```vim

```

--------------------------------

### Install Git Package (Shell)

Source: https://github.com/tritondatacenter/smartos-live/blob/master/README.md

This command installs the 'git' package using the `pkgin` package manager. Git is a prerequisite for cloning the SmartOS Live repository and managing source code. The '-y' flag automatically confirms the installation.

```shell
$ pfexec pkgin -y in git
```

--------------------------------

### Configure VM Parameters for Firewall Integration

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/fw/man/fwadm.8.md

Example JSON configuration for a VM, including firewall settings, NIC definitions, and tags that trigger specific firewall rules.

```json
{
    "brand": "joyent",
    "image_uuid": "7b0b4140-6e98-11e5-b1ae-ff68fe257228",
    "firewall_enabled": true,
    "nics": [
      {
        "nic_tag": "external",
        "ip": "10.88.88.59",
        "netmask": "255.255.255.0",
        "gateway": "10.88.88.2",
        "primary": true
      }
    ],
    "owner_uuid": "e6c73bd2-fae4-4e0a-af76-2c05d088b066",
    "ram": 128,
    "tags": {
        "blocksmtp": true
    },
    "uuid": "60e90d15-fb48-4bb9-90e6-1e1bb8269d1e"
}
```

--------------------------------

### Installation and Testing via NPM

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/node_modules/tap/node_modules/deep-equal/README.markdown

Standard commands to install the deep-equal package and execute the test suite using the Node Package Manager.

```bash
npm install deep-equal
```

```bash
npm test
```

--------------------------------

### Get Help using fwadm

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/fw/man/fwadm.8.md

Prints general help information for the fwadm tool or specific help for a given command.

```bash
fwadm help [command]
```

--------------------------------

### Update VM Tags via vmadm

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/fw/man/fwadm.8.md

Command-line example demonstrating how to update VM tags using vmadm, which subsequently triggers an update to firewall rules via fwadm.

```bash
echo '{ "set_tags": { "role": "webserver" } }' | vmadm update 60e90d15-fb48-4bb9-90e6-1e1bb8269d1e
```

--------------------------------

### Bunyan: Loggly Integration Example

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/node-bunyan/TODO.md

Providing an example of integrating Bunyan with Loggly, potentially using raw streams or other compatible methods like hook.io.

```javascript
# loggly example using raw streams, hook.io?, whatever.
```

--------------------------------

### Bash Installation Command

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/fw/test/node_modules/brace-expansion/README.md

Provides the command to install the brace-expansion library using npm, the Node Package Manager. This is the standard method for adding the library to a JavaScript project.

```bash
npm install brace-expansion
```

--------------------------------

### Example of minimatch with Options

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/node_modules/tap/node_modules/glob/node_modules/minimatch/README.md

Shows a practical application of the `minimatch` function with the `matchBase` option set to true, which affects how patterns without slashes are matched against file paths.

```javascript
var isJS = minimatch(file, "*.js", { matchBase: true })
```

--------------------------------

### Install prerequisite package upgrades

Source: https://github.com/tritondatacenter/smartos-live/blob/master/docs/dev-upgrade.md

Updates core package management utilities to ensure compatibility with the new repository structure before performing a full system upgrade.

```bash
pkg_add -U libarchive pkg_install pkgin
```

--------------------------------

### Calculate code coverage with Bunker

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/node_modules/tap/node_modules/runforcover/node_modules/bunker/README.markdown

This example demonstrates how to initialize a Bunker instance with source code, listen for node execution events to track counts, and run the instrumented code.

```javascript
var bunker = require('bunker');
var b = bunker('var x = 0; for (var i = 0; i < 30; i++) { x++ }');

var counts = {};

b.on('node', function (node) {
    if (!counts[node.id]) {
        counts[node.id] = { times : 0, node : node };
    }
    counts[node.id].times ++;
});

b.run();

Object.keys(counts).forEach(function (key) {
    var count = counts[key];
    console.log(count.times + ' : ' + count.node.source());
});
```

--------------------------------

### Manage and inspect bootable ZFS pools

Source: https://github.com/tritondatacenter/smartos-live/blob/master/man/usr/share/man/man8/piadm.8.md

Demonstrates how to check bootable status, list installed Platform Images, and inspect the directory structure of a bootable ZFS pool.

```shell
[root@smartos ~]# piadm bootable
standalone                     ==> BIOS and UEFI
zones                          ==> non-bootable
[root@smartos ~]# piadm list
PI STAMP           BOOTABLE FILESYSTEM            BOOT IMAGE   NOW   NEXT
20200714T195617Z   standalone/boot                next         yes   yes
[root@smartos ~]# ls -l /standalone/boot
total 7
lrwxrwxrwx   1 root     root          23 Jul 15 04:22 boot -> ./boot-20200714T195617Z
drwxr-xr-x   4 root     root          15 Jul 15 04:12 boot-20200714T195617Z
drwxr-xr-x   3 root     root           3 Jul 15 04:22 etc
lrwxrwxrwx   1 root     root          27 Jul 15 04:22 platform -> ./platform-20200714T195617Z
drwxr-xr-x   4 root     root          5 Jul 15 04:12 platform-20200714T195617Z
```

--------------------------------

### Get Zone Name by ID and ID by Name using node-zonename

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/node-zonename/README.md

This example demonstrates how to look up zone information by providing either a zone ID or a zone name. It uses `getzonenamebyid(id)` to get the name from an ID and `getzoneidbyname(name)` to get the ID from a name. An error is thrown if the provided ID or name is invalid or not found.

```javascript
var zone = require('node-zonename');

zone.getzonenamebyid(1);
// => "39f07647-6f8a-4671-898c-104f64501ac9"

zone.getzoneidbyname("39f07647-6f8a-4671-898c-104f64501ac9");
// => 1
```

--------------------------------

### POST /imgadm/create

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/img/man/imgadm.8.md

Creates a new image from an existing virtual machine, optionally running a preparation script inside the VM.

```APIDOC
## POST /imgadm/create

### Description
Creates an image from a specified VM. Supports automatic preparation via scripts or manual preparation workflows.

### Method
POST

### Endpoint
imgadm create [<options>] <vm-uuid> [<manifest-field>=<value> ...]

### Parameters
#### Path Parameters
- **vm-uuid** (string) - Required - The UUID of the source VM.

#### Request Body
- **-m** (json) - Optional - Path to a JSON file containing manifest data.
- **-c** (string) - Optional - Compression type: "none", "gzip", "bzip2", or "xz".
- **-s** (string) - Optional - Path to a script to execute inside the VM for preparation.
- **-i** (boolean) - Optional - Build an incremental image.

### Response
#### Success Response (200)
- **image_uuid** (string) - The UUID of the newly created image.
- **manifest_path** (string) - Location of the generated manifest file.
```

--------------------------------

### Get Current Zone Name and ID using node-zonename

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/node-zonename/README.md

This example shows how to retrieve the current zone's name and ID using the node-zonename module. It utilizes the `getzonename()` and `getzoneid()` functions, which are direct wrappers for the underlying C library functions.

```javascript
var zone = require('node-zonename');

zone.getzonename();
// => "global"

zone.getzoneid();
// => 0
```

--------------------------------

### Create Bootable Pool and Set Platform Image (SmartOS)

Source: https://github.com/tritondatacenter/smartos-live/blob/master/man/usr/share/man/man8/piadm.8.md

This example demonstrates creating a new bootable ZFS pool and then using piadm to make a specific platform image bootable. It shows the initial state, the command to enable a PI, and the resulting state after the PI is set to be loaded on the next boot.

```shell
[root@smartos ~]# zpool create -f -B standalone c1t1d0
 [root@smartos ~]# piadm bootable
 standalone                     ==> non-bootable
 zones                          ==> non-bootable
 [root@smartos ~]# piadm -v bootable -e -i latest standalone
 Installing PI 20200701T231659Z
 Platform Image 20200701T231659Z will be loaded on next boot,
     with a new boot image,
     boot image  20200701T231659Z
 [root@smartos ~]# piadm bootable
 standalone                     ==> BIOS and UEFI
 zones                          ==> non-bootable
 [root@smartos ~]# piadm list
 PI STAMP           BOOTABLE FILESYSTEM            BOOT IMAGE   NOW   NEXT
 20200701T231659Z   standalone/boot                next         no    yes
 [root@smartos ~]#
```

--------------------------------

### Manage VMs with VM.js in Node.js

Source: https://context7.com/tritondatacenter/smartos-live/llms.txt

This JavaScript code demonstrates how to use the VM.js library to interact with virtual machines. It covers common operations like listing, creating, updating, starting, stopping, rebooting, and deleting VMs. The library requires Node.js and the VM.js module to be installed.

```javascript
var VM = require('/usr/vm/node_modules/VM');

// List all VMs
VM.lookup({}, { fields: ['uuid', 'alias', 'state', 'ram'] }, function(err, vms) {
    if (err) {
        console.error('Error:', err.message);
        return;
    }
    vms.forEach(function(vm) {
        console.log('%s (%s): %s - %dMB RAM',
            vm.uuid, vm.alias, vm.state, vm.ram);
    });
});

// Lookup VMs with filters
VM.lookup({ state: 'running', brand: 'joyent' }, {}, function(err, vms) {
    console.log('Running joyent zones:', vms.length);
});

// Load single VM by UUID
VM.load('54f1cc77-68f1-42ab-acac-5c4f64f5d6e0', function(err, vm) {
    if (err) {
        console.error('VM not found:', err.message);
        return;
    }
    console.log('VM details:', JSON.stringify(vm, null, 2));
});

// Create a new VM
var vmspec = {
    brand: 'joyent',
    image_uuid: '2f1dc911-6401-4fa4-8e9d-67ea2e39c271',
    alias: 'my-api-server',
    hostname: 'api.example.com',
    max_physical_memory: 1024,
    quota: 25,
    nics: [{
        nic_tag: 'admin',
        ip: '10.88.88.100',
        netmask: '255.255.255.0',
        gateway: '10.88.88.1',
        primary: true
    }],
    customer_metadata: {
        'user-script': '#!/bin/bash\necho "Hello from SmartOS"'
    }
};

VM.create(vmspec, function(err, info) {
    if (err) {
        console.error('Create failed:', err.message);
        return;
    }
    console.log('Created VM:', info.uuid);
});

// Update VM properties
VM.update('54f1cc77-68f1-42ab-acac-5c4f64f5d6e0', {
    max_physical_memory: 2048,
    alias: 'updated-alias',
    quota: 50
}, function(err) {
    if (err) {
        console.error('Update failed:', err.message);
        return;
    }
    console.log('VM updated successfully');
});

// Start/Stop/Reboot operations
VM.start('54f1cc77-68f1-42ab-acac-5c4f64f5d6e0', {}, function(err) {
    if (err) console.error('Start failed:', err.message);
    else console.log('VM started');
});

VM.stop('54f1cc77-68f1-42ab-acac-5c4f64f5d6e0', { timeout: 60 }, function(err) {
    if (err) console.error('Stop failed:', err.message);
    else console.log('VM stopped');
});

VM.reboot('54f1cc77-68f1-42ab-acac-5c4f64f5d6e0', {}, function(err) {
    if (err) console.error('Reboot failed:', err.message);
    else console.log('VM rebooted');
});

// Delete VM
VM.delete('54f1cc77-68f1-42ab-acac-5c4f64f5d6e0', function(err) {
    if (err) console.error('Delete failed:', err.message);
    else console.log('VM deleted');
});

```

--------------------------------

### Install Bunyan via NPM

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/node-bunyan/README.md

Provides the command to install the Bunyan library into a Node.js project. It is recommended to install globally to access the CLI tool.

```bash
npm install bunyan
```

--------------------------------

### Build SmartOS from Source

Source: https://github.com/tritondatacenter/smartos-live/blob/master/README.md

Commands to clone the repository, configure the build environment, and compile the SmartOS live image. This process requires a compatible build environment and generates the final output in the output directory.

```bash
git clone https://github.com/TritonDataCenter/smartos-live.git
cd smartos-live
./configure
gmake world
gmake live
ls output/
```

--------------------------------

### Clone SmartOS Live Repository and Initiate Build (Shell)

Source: https://github.com/tritondatacenter/smartos-live/blob/master/README.md

This sequence of commands clones the SmartOS Live repository from GitHub, navigates into the repository directory, configures the build environment, and then initiates the build process for the live image. The 'gmake live' command assembles the platform into a tarball.

```shell
$ git clone https://github.com/TritonDataCenter/smartos-live
$ cd smartos-live
$ ./configure
$ gmake live
```

--------------------------------

### Bunyan API: Serializer Support Examples

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/node-bunyan/TODO.md

Examples and considerations for Bunyan's serializer support, including a restify-server.js example and handling differential HTTP client/server request/response objects.

```javascript
# serializer support:
#     - restify-server.js example -> restifyReq ? or have `req` detect that.
#       That is nicer for the "use all standard ones". *Does* restify req
#       have anything special?
#     - differential HTTP *client* req/res with *server* req/res.
```

--------------------------------

### Create VM Image with imgadm

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/img/man/imgadm.8.md

Creates a VM image from a prepared and shutdown VM. It can accept manifest data via stdin or as arguments, and allows specifying an output path or publishing directly to an IMGAPI server. A `prepare-image` script can be provided to automate VM preparation.

```bash
# Create an image from VM 5f7a53e9-fc4d-d94b-9205-9ff110742aaf.
echo '{"name": "foo", "version": "1.0.0"}' \
    | imgadm create -m - -s /path/to/prepare-image \
        5f7a53e9-fc4d-d94b-9205-9ff110742aaf

# Specify manifest data as arguments.
imgadm create -s prep-image 5f7a53e9-fc4d-d94b-9205-9ff110742aaf \
    name=foo version=1.0.0

# Write the manifest and image file to "/var/tmp".
imgadm create -s prep-image 5f7a53e9-fc4d-d94b-9205-9ff110742aaf \
    name=foo version=1.0.0 -o /var/tmp

# Publish directly to an image repository (IMGAPI server).
imgadm create -s prep-image 5f7a53e9-fc4d-d94b-9205-9ff110742aaf \
    name=foo version=1.0.0 --publish https://images.example.com

# Create an image from the prepared and shutdown VM
# 5f7a53e9-fc4d-d94b-9205-9ff110742aaf, using some manifest JSON
# data from stdin.
echo '{"name": "foo", "version": "1.0.0"}' \
    | imgadm create -m - 5f7a53e9-fc4d-d94b-9205-9ff110742aaf
```

--------------------------------

### POST /imgadm/create

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/img/man/imgadm.8.md

Creates an image from a prepared and shutdown virtual machine. This process captures the VM state and metadata into a manifest for future deployment.

```APIDOC
## POST imgadm create

### Description
Creates an image from a specified VM UUID. The process can optionally publish the result directly to an IMGAPI server or output files to a local directory.

### Method
POST (CLI Command)

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the prepared and shutdown VM.

#### Options
- **-p, --publish** (url) - Optional - Publish directly to the given IMGAPI server.
- **-o** (path) - Optional - Output directory for manifest and image file.
- **-s** (path) - Optional - Path to the prepare-image script.
- **-m** (json/file) - Optional - Manifest data provided via stdin or file.

### Request Example
```bash
echo '{"name": "foo", "version": "1.0.0"}' | imgadm create -m - 5f7a53e9-fc4d-d94b-9205-9ff110742aaf
```

### Response
#### Success Response (0)
- **status** (string) - Image creation success message.

#### Response Example
```json
{
  "status": "success",
  "image_uuid": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}
```
```

--------------------------------

### Manage SmartOS VM Images with imgadm.js

Source: https://context7.com/tritondatacenter/smartos-live/llms.txt

Demonstrates how to initialize the imgadm tool and perform common administrative tasks including listing local images, retrieving specific image manifests, importing images from sources, and deleting existing images.

```javascript
var imgadm = require('/usr/img/lib/imgadm');
var bunyan = require('bunyan');

// Create logger for imgadm operations
var log = bunyan.createLogger({
    name: 'imgadm-example',
    level: 'info'
});

// Initialize imgadm tool
imgadm.createTool({ log: log }, function(err, tool) {
    if (err) {
        console.error('Failed to create tool:', err.message);
        return;
    }

    // List installed images
    tool.listImages(function(err, images) {
        if (err) {
            console.error('Error listing images:', err.message);
            return;
        }
        images.forEach(function(img) {
            console.log('%s %s@%s (%s)',
                img.manifest.uuid,
                img.manifest.name,
                img.manifest.version,
                img.manifest.os);
        });
    });

    // Get specific image details
    tool.getImage({
        uuid: '2f1dc911-6401-4fa4-8e9d-67ea2e39c271',
        zpool: 'zones'
    }, function(err, image) {
        if (err) {
            console.error('Image not found:', err.message);
            return;
        }
        console.log('Image manifest:', JSON.stringify(image.manifest, null, 2));
        console.log('Clones:', image.clones);
    });

    // Import image from source
    tool.importImage({
        uuid: '2f1dc911-6401-4fa4-8e9d-67ea2e39c271',
        zpool: 'zones'
    }, function(err) {
        if (err) {
            console.error('Import failed:', err.message);
            return;
        }
        console.log('Image imported successfully');
    });

    // List available images from sources
    tool.sourcesList(function(err, sources) {
        if (err) {
            console.error('Error:', err.message);
            return;
        }
        sources.forEach(function(source) {
            console.log('Source: %s (%s)', source.url, source.type);
        });
    });

    // Delete installed image
    tool.deleteImage({
        uuid: 'old-image-uuid',
        zpool: 'zones'
    }, function(err) {
        if (err) {
            console.error('Delete failed:', err.message);
            return;
        }
        console.log('Image deleted');
    });
});
```

--------------------------------

### Install mkdirp via npm

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/node_modules/tap/node_modules/mkdirp/readme.markdown

Command to install the mkdirp package using the Node Package Manager.

```bash
npm install mkdirp
```

--------------------------------

### Development and Build Commands

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/node-qlocker/README.md

Standard commands for building, testing, and verifying the node-qlocker project using make and npm.

```bash
make
npm install
npm test
```

--------------------------------

### Initialize JavaScript Runtime and Context

Source: https://github.com/tritondatacenter/smartos-live/blob/master/tools/javascriptlint/spidermonkey/src/README.html

Demonstrates the essential steps to initialize a JavaScript runtime and context using the JS API. It includes setting the stack chunk size and creating a global object to support standard classes.

```C
/*
 * Tune this to avoid wasting space for shallow stacks, while saving on
 * malloc overhead/fragmentation for deep or highly-variable stacks.
 */
#define STACK_CHUNK_SIZE    8192

JSRuntime *rt;
JSContext *cx;

/* You need a runtime and one or more contexts to do anything with JS. */
rt = JS_NewRuntime(0x400000L);
if (!rt)
    fail("can't create JavaScript runtime");
cx = JS_NewContext(rt, STACK_CHUNK_SIZE);
if (!cx)
    fail("can't create JavaScript context");

/*
 * The context definitely wants a global object, in order to have standard
 * classes and functions like Date and parseInt.
 */
JSObject *globalObj;

globalObj = JS_NewObject(cx, &my_global_class, 0, 0);
JS_InitStandardClasses(cx, globalObj);
```

--------------------------------

### Install Browserify and Bunyan

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/node-bunyan/README.md

Installs Browserify and Bunyan using npm. These are the core dependencies for bundling Node.js modules and using Bunyan logging in the browser.

```bash
$ npm install browserify bunyan
```

--------------------------------

### Basic TAP Test Example in Node.js

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/node_modules/tap/README.md

Demonstrates how to use the tap module to define and run tests. It includes various assertion types like equal, deepEqual, type, ok, and notOk. It also shows how to create nested child tests and skip individual assertions or entire test blocks.

```javascript
var test = require("tap").test

test("make sure the thingie is a thing", function (t) {
  t.equal(thingie, "thing", "thingie should be thing")
  t.deepEqual(array, ["foo", "bar"], "array has foo and bar elements")
  t.deepEqual(object, {foo: 42}, "object has foo property")
  t.type(thingie, "string", "type of thingie is string")
  t.ok(true, "this is always true")
  t.notOk(false, "this is never true")
  t.test("a child test", function (t) {
    t.equal(this, superEasy, "right!?")
    t.similar(7, 2, "ever notice 7 is kinda like 2?", {todo: true})
    t.test("so skippable", {skip: true}, function (t) {
      t.plan(1) // only one test in this block
      t.ok(true, "but when the flag changes, it'll pass")
      // no need to end, since we had a plan.
    })
    t.end()
  })
  t.ok(99, "can also skip individual assertions", {skip: true})
  // end lets it know it's over.
  t.end()
})

test("another one", function (t) {
  t.plan(1)
  t.ok(true, "It's ok to plan, and also end.  Watch.")
  t.end() // but it must match the plan!
})
```

--------------------------------

### Bunyan: Future Documentation and Examples

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/node-bunyan/TODO.md

Plans for comprehensive documentation and improved examples for the Bunyan logging library, covering advanced features and use cases.

```markdown
# someday/maybe

- full-on docs
- better examples/
```

--------------------------------

### Install EJS using npm

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/deps/ejs/Readme.md

This command installs the EJS templating engine using npm, the Node Package Manager. It's a prerequisite for using EJS in a Node.js project.

```bash
$ npm install ejs
```

--------------------------------

### Initialize bldenv for illumos development

Source: https://github.com/tritondatacenter/smartos-live/blob/master/README.md

Commands to navigate to the illumos source directory and initialize the build environment using the bldenv tool. This setup allows for incremental compilation of individual components.

```bash
cd projects/illumos/usr/src
./tools/proto/root_i386-nd/opt/onbld/bin/bldenv ../../illumos.sh
```

--------------------------------

### Install UglifyJS from GitHub

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/node_modules/tap/node_modules/runforcover/node_modules/bunker/node_modules/burrito/node_modules/uglify-js/README.org

Details the steps to clone the UglifyJS repository from GitHub and make it available as a module for Node.js. This method is useful for installing the latest development version.

```sh
## clone the repository
mkdir -p /where/you/wanna/put/it
cd /where/you/wanna/put/it
git clone https://github.com/mishoo/UglifyJS.git

## make the module available to Node
mkdir -p ~/.node_libraries/
cd ~/.node_libraries/
ln -s /where/you/wanna/put/it/UglifyJS/uglify-js.js
```

--------------------------------

### Disk Configuration Parameters

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/man/vmadm.8.md

This section details the parameters available for configuring individual disks within a virtual machine's configuration.

```APIDOC
## Disk Configuration Parameters

This section details the parameters available for configuring individual disks within a virtual machine's configuration.

### `disks.*.block_size`

Specifies the ZFS block size for the disk. This property cannot be changed after disk creation without destroying and recreating the disk. It cannot be set on disks that have an `image_uuid` parameter.

- **Type**: integer (block size in bytes, 512 to 131072, must be power of 2)
- **VM Type**: HVM
- **Creatable**: yes
- **Updatable**: no (except when adding new disks)
- **Default**: 8192

### `disks.*.boot`

Specifies whether this disk should be bootable. Only one disk in a VM should be bootable.

- **Type**: boolean
- **VM Type**: HVM
- **Creatable**: yes
- **Updatable**: yes
- **Default**: no

### `disks.*.compression`

Specifies a compression algorithm used for this disk. This affects a single disk on the VM.

- **Type**: string (one of: "on,off,gzip,gzip-N,lz4,lzjb,zle")
- **VM Type**: HVM
- **Creatable**: yes
- **Updatable**: yes
- **Default**: off

### `disks.*.guest_block_size`

Specifies the device block size reported to the guest. Can be a single value or a string like "logical_size/physical_size".

- **Type**: string (of the form "NNN" or "NNN/NNN")
- **VM Type**: bhyve
- **Creatable**: yes
- **Updatable**: yes
- **Default**: no

### `disks.*.nocreate`

Indicates whether or not the disk should be created. Only applicable for disks with media type 'disk' and can only be set during disk creation.

- **Type**: boolean
- **VM Type**: HVM
- **Creatable**: yes
- **Updatable**: no (except when adding new disks)
- **Default**: false

### `disks.*.image_name`

Name of the dataset from which to clone this VM's disk. Specify this along with `image_size` and `image_uuid`, or `size` for a disk.

- **Type**: string
- **VM Type**: HVM
- **Creatable**: yes
- **Updatable**: yes
- **Default**: no

### `disks.*.image_size`

The size of the image from which to create this disk (in MiB). Required when `image_uuid` is provided and `size` is not.

- **Type**: integer (size in MiB)
- **VM Type**: HVM
- **Creatable**: yes
- **Updatable**: yes
- **Default**: no (loaded from imgadm if possible)

### `disks.*.image_uuid`

UUID of the dataset from which to clone this VM's disk. This image's UUID must be listed in `imgadm list` output.

- **Type**: string (UUID)
- **VM Type**: HVM
- **Creatable**: yes
- **Updatable**: yes
- **Default**: no

### `disks.*.notrim`

Explicitly disables TRIM functionality (UNMAP/DISCARD) for the disk in the guest. Corresponds to the bhyve `nodelete` block-device-option.

- **Type**: boolean
- **VM Type**: bhyve
- **Creatable**: yes
- **Updatable**: yes
- **Default**: no

### `disks.*.pci_slot`

Specifies the virtual PCI slot that this disk will occupy. Bhyve places each disk into a PCI slot identified by the PCI bus, device, and function.
```

--------------------------------

### Install UglifyJS via NPM

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/node_modules/tap/node_modules/runforcover/node_modules/bunker/node_modules/burrito/node_modules/uglify-js/README.org

Provides the command to install the UglifyJS JavaScript minifier using the Node Package Manager (NPM). This is the recommended method for integrating UglifyJS into Node.js projects.

```sh
npm install uglify-js
```

--------------------------------

### Lifting Variables Transformation Example

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/node_modules/tap/node_modules/runforcover/node_modules/bunker/node_modules/burrito/node_modules/uglify-js/README.org

Illustrates the 'lift_vars' transformation performed by UglifyJS, which moves variable declarations to the top of their scope and consolidates them. This example shows the 'before' and 'after' states of a function.

```javascript
function f(a, b, c, d, e) {
    var q;
    var w;
    w = 10;
    q = 20;
    for (var i = 1; i < 10; ++i) {
        var boo = foo(a);
    }
    for (var i = 0; i < 1; ++i) {
        var boo = bar(c);
    }
    function foo(){ ... }
    function bar(){ ... }
    function baz(){ ... }
}

// transforms into ==> 

function f(a, b, c) {
    var i, boo, w = 10, q = 20;
    for (i = 1; i < 10; ++i) {
        boo = foo(a);
    }
    for (i = 0; i < 1; ++i) {
        boo = bar(c);
    }
    function foo() { ... }
    function bar() { ... }
}
```

--------------------------------

### Shell: Install deep-is using npm

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/node_modules/tap/node_modules/difflet/node_modules/deep-is/README.markdown

Installs the 'deep-is' module using the Node Package Manager (npm). This command should be run in a terminal within your project directory.

```bash
npm install deep-is
```

--------------------------------

### Configure Command-Line Shorthands

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/node_modules/tap/node_modules/nopt/README.md

Shows how to map short flags to full command-line arguments, allowing for complex command expansion.

```json
{
  "s": ["--loglevel", "silent"],
  "g": "--global",
  "f": "--force",
  "p": "--parseable",
  "l": "--long"
}
```

```bash
npm ls -sgflp
```

--------------------------------

### Upgrade pkgin configuration

Source: https://github.com/tritondatacenter/smartos-live/blob/master/docs/dev-upgrade.md

Extracts the bootstrap upgrade archive to the root directory to update the system package management environment. Requires prior backup of configuration files in /opt/local/etc.

```bash
gtar -xzvf ./bootstrap-2024Q4-x86_64-upgrade.tar.gz -C /.
```

--------------------------------

### EJS Filter Example: First and Capitalize

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/deps/ejs/Readme.md

This example uses EJS filters to process an array of users. The 'first' filter selects the first user object, and the 'capitalize' filter converts their name to title case.

```html
<p><%=: users | first | capitalize %></p>
```

--------------------------------

### Prepare Image Script Contract for imgadm

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/img/man/imgadm.8.md

Defines the contract for a `prepare-image` script used by `imgadm create`. The script must set specific metadata states ('running', 'success', 'error') and shut down the VM upon completion or failure. This ensures orderly VM preparation and allows `imgadm create` to fail fast.

```bash
# 1. Set initial state
mdata-put prepare-image:state running

# ... script logic ...

# 2. On successful completion
mdata-put prepare-image:state success

# OR

# 3. On error
mdata-put prepare-image:state error
mdata-put prepare-image:error '... some error details ...'

# 4. Shutdown the VM when done (implicitly or explicitly)
```

--------------------------------

### EJS Filter Example: Map and Join

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/vm/node_modules/nodeunit/deps/ejs/Readme.md

An example showcasing EJS filters to process an array of user objects. The 'map' filter extracts the 'name' property from each user, and the 'join' filter concatenates them into a comma-separated string.

```html
<p><%=: users | map:'name' | join %></p>
```

--------------------------------

### Ineffective Firewall Rule Examples

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/fw/tools/fwrule/docs/rules.md

Provides examples of firewall rules that may not have the intended effect due to SmartOS's default rule sets. Understanding these limitations helps in writing effective firewall configurations.

```firewall
FROM any TO any ALLOW tcp port 22
```

```firewall
FROM ip 192.168.1.3 TO subnet 192.168.1.0/24 ALLOW tcp port 22
```

--------------------------------

### SmartOS Firewall Rule Syntax Examples

Source: https://github.com/tritondatacenter/smartos-live/blob/master/src/fw/man/fwrule.7.md

Examples of the domain-specific language used to define firewall rules. These rules support various targets including VMs, subnets, tags, and IP addresses.

```text
FROM any to vm 04128191-d2cb-43fc-a970-e4deefe970d8 ALLOW tcp port 80
FROM all vms to (ip 10.2.0.1 OR ip fd22::1234) BLOCK tcp port 25
FROM subnet 10.8.0.0/16 TO vm 0f570678-c007-4610-a2c0-bbfcaab9f4e6 ALLOW tcp port 443
FROM tag role = db TO tag role = www ALLOW tcp port 5432
FROM (vm 163dcedb-828d-43c9-b076-625423250ee2 OR tag db) TO (subnet 10.2.2.0/24 OR ip 10.3.0.1) BLOCK tcp port 443
```