View Source

This page can move to the normal documentation space after we clean it up.


h1. Background

[Bryan's talk (both entertaining and informative)|] ([slides|])

h1. Getting Started

h2. Platform Version

For best results, run the latest SmartOS release available.

h2. Import images

The lx zone images are on so make sure that's one of your image sources. Then you can import images:
imgadm sources -a
imgadm avail | grep lx-dataset # See available images
imgadm import 05140a7e-279f-11e6-aedf-47d4f69d2887 # ubuntu-16.04 20160601

h2. Create A Zone

Create a zone (replace the nic values with ones appropriate for your network)

{tip}If you're not sure what these values mean or what units they are in, check out the [vmadm man page|]{tip}
"alias": "lxtest",
"brand": "lx",
"kernel_version": "4.3.0",
"max_physical_memory": 2048,
"quota": 10,
"image_uuid": "05140a7e-279f-11e6-aedf-47d4f69d2887",
"resolvers": ["",""],
"nics": [
"nic_tag": "external",
"ips": ["dhcp"],
"primary": true

h1. Cool Tech Demos

A selection of impressive demonstrations of the LX brand's capabilities. Please add your favorites here.

Show your friends:

* X11 forwarded [Firefox|] and [Thunderbird|] in lx32 zone
* Plex Media Server usable on lx32 and lx64 (DLNA and some other bits broken still)
* dtrace a linux binary
* [Video of docker in SDC (coming soon to the JPC)|]
* (your favorite demo here)

h1. Networking

AF_INET and AF_INET6 mostly working (2014-12-19). Still have some sockopts missing.

ipadm is not working inside the lx brand, /native/sbin/ifconfig is usable.

h2. Enabling IPv6 SLAAC auto configuration

Add "addrconf" to the "ips" array for the NIC to perform SLAAC and/or DHCPv6 as appropriate.

h1. X11 forwarding

This is working fine on both 32-bit and 64-bit. After pmooney's AF_INET6 commit this is working fine out of the box\!

h1. Debugging

If debugging LX branded zones, first watch this video: [Debugging LX branded zones on SmartOS|]

h2. DTrace

h3. Enabling {{lx_debug}} probes

As the video above mentioned, probes associated with {{lx_debug}} (that is, output associated with the {{LX_DEBUG}} environment variable) are turned on it {{LX_DTRACE}} is set to a non-zero value in the environment. However, this is not helpful if in a context that is hard to set environment variable (e.g., early in boot). The video above neglected to mention how to enable DTrace probes in this case. To do this, you must first change the disposition of the brand to enable these by default by modifying the binary. From the global zone, do the following:

# cp /usr/lib/amd64/ /var/tmp
# cp /usr/lib/amd64/ /var/tmp/$$
# echo "lx_dtrace_lazyload?W 0" | mdb -w /var/tmp/$$
# mount -O -F lofs /var/tmp/$$ /usr/lib/amd64/

(If debugging 32-bit, the {{}} that should be copied and mounted over should be {{/usr/lib/}} not {{/usr/lib/amd64/}}.)

At that point, {{lx{}}}{{[pid]}}{{:::debug}} probes should show up as processes start, which will allow you to see where things are failing:

# dtrace -Zqn lx*:::debug'{printf("%s", copyinstr(arg0))}'

(String size and switch rate should be adjusted up if truncated strings or drops are seen.)

When debugging a new distro or otherwise debugging the death of processes before you can login, you can

h3. hunting for unsupported syscalls

These need to be run from the GZ:

{code:title=lxunsup.d}#!/usr/sbin/dtrace -s

#pragma D option quiet

printf("%6s %20s %s\n", "PID", "NAME", "CALL")

printf("%6d %20s %S\n", pid, execname, stringof(arg0));

dtrace -n 'sdt:lx_brand::brand-lx-unsupported { @num[execname,stringof(arg0)] = count() }'

dtrace -n 'lx-syscall::setsockopt:entry /arg1 == 0 && arg2 == 35/ { trace(arg4) }'

{note:title=harmless unsupported syscalls}{note}
|| syscall \\ || note \\ ||
| prctl(PR_SET_DUMPABLE) | allow process to enable coredumps, should have no functional impact \\ |
| prctl option 4 \\ | same as PR_SET_DUMPABLE |
| set_robust_list / get_robust_list | part of libc initialization, but if the feature is never used, then it doesn't really end up mattering. |
| futex 0x9 | usespace mutex call, mostly harmless \\ |
| socket flag MSG_CMSG_CLOEXEC | auto close fd's... dbus spams these a lot. Looks like they get closed anyway. \\ |
| ioctl 0xc020660b (fiemap) | used to find holes in files by querying the inode extend info, apt tries to use this. have not noticed any impact. \\ |

h3. probing socket options

This is handy for figuring out why a networking app is not behaving properly.

{code:title=lxsockopt.d}#!/usr/sbin/dtrace -s

#pragma D option quiet

PROTO values can be found here:
SOCKOPT values can be found here:
printf("%6s %20s %5s %s\n", "PID", "NAME", "PROTO", "SOCKOPT");

printf("%6d %20s %5d %d\n", pid, execname, arg1, arg2);

{code}dtrace -n 'lx-syscall::setsockopt:entry { @num[execname,arg2] = count() }'{code}

h1. Docker

[Bryan's talk and demo of sdc-docker|]

* []
* []
* []
* []

h1. Vagrant

Initial support for lx brand is complete:
* [Quickstart example|]
* []

h1. Random Notes

h2. Getting /native binaries to work

export PATH=$PATH:/native/usr/bin:/native/usr/sbin:/native/sbin

Now truss should work. Note that some native binaries try to execute other native binaries. (For example, {{arp}} tries to execute {{netstat}}.) For programs written in C, this can be fixed, so please file a ticket if it doesn't work in a recent release.

h2. Creating your own zone dataset

* []
* []
* []
* []
* []
* []

h2. Joyent CI builds

If you run into a new bug, someone might ask you to try the latest CI build after it's been fixed. This is how.

The Joyent CI system constantly rebuilds the platform tarball when there are new commits.
You can extract that image and put into place on e.g. an existing SmartOS USB stick to obtain the latest and greatest code from Joyent.

You can download that platform tarball like so:

LATEST=$(curl ${MANTA_URL}/Joyent_Dev/public/builds/platform/master-latest)
curl -O ${MANTA_URL}${LATEST}/platform/platform-master-${LATEST##*-}.tgz

To update an existing SmartOS USB stick:
# Extract that tarball onto your USB stick (you'll get a directory named "platform-<datestamp>")
# Move aside the directory named "platform" to e.g. "platform-orig"
# Rename "platform-<datestamp>" to "platform"
# Boot from your USB stick