Awesome

Table of Contents

• nash
• Show time!
  • Useful stuff
  • Why nash scripts are reliable?
  • Installation
    • Release
      • Linux
    • Master
  • Getting started
• Accessing command line args
• Namespace features
• OK, but how scripts should look like?
• Didn't work?
• Language specification
• Some Bash comparisons
• Security
• Installing libraries
• Releasing
• Want to contribute?

nash

Nash is a system shell, inspired by plan9 rc, that makes it easy to create reliable and safe scripts taking advantages of operating systems namespaces (on linux and plan9) in an idiomatic way.

Useful stuff

• nashfmt: Formats nash code (like gofmt) but no code styling defined yet (see Installation section).
• nashcomplete: Autocomplete done in nash script.
• Dotnash: Nash profile customizations (e.g: prompt, aliases, etc)
• nash-mode: Emacs major mode integrated with nashfmt.

Why nash scripts are reliable?

1. Nash aborts at first non-success status of commands;
2. Nash aborts at first unbound variable;
3. It's possible to check the result status of every component of a pipe;
4. no eval;
5. Strings are pure strings (no evaluation of variables);
6. No wildcards (globbing) of files; ('rm *' removes a file called '*');
   • On windows, the terminal does the globbing when in interactive mode.
   • On unix there's libs/completions to achieve something similar.
7. No obscure syntax;
8. Support tooling for indent/format and statically analyze the scripts;

Installation

Nash uses two environment variables: NASHROOT to find the standard nash library and NASHPATH to find libraries in general (like user's code).

It is important to have two different paths since this will allow you to upgrade nash (overwrite nash stdlib) without risking lost your code.

If NASHPATH is not set, a default of $HOME/nash will be assumed ($HOMEPATH/nash on windows). If NASHROOT is not set, a default of $HOME/nashroot will be assumed ($HOMEPATH/nashroot on windows).

The libraries lookup dir will be $NASHPATH/lib. The standard library lookup dir will be $NASHROOT/stdlib.

After installing the nash binary will be located at $NASHROOT/bin.

Installing a Release

Installing is so stupid that we provide small scripts to do it. If your platform is not supported take a look at the existent ones and send a MR with the script for your platform.

Unix

If you run a unix based machine (Linux, Darwin/OSX, *BSD, etc) you can use the script below:

Run:

./hack/install/unix.sh

Master

Run:

make install

Getting started

Nash syntax resembles a common shell:

nash
λ> echo "hello world"
hello world

Pipes works like borne shell and derivations:

λ> cat spec.ebnf | wc -l
108

Output redirection works like Plan9 rc, but not only for filenames. It supports output redirection to tcp, udp and unix network protocols (unix sockets are not supported on windows).

# stdout to log.out, stderr to log.err
λ> ./daemon >[1] log.out >[2] log.err
# stderr pointing to stdout
λ> ./daemon-logall >[2=1]
# stdout to /dev/null
λ> ./daemon-quiet >[1=]
# stdout and stderr to tcp address
λ> ./daemon >[1] "udp://syslog:6666" >[2=1]
# stdout to unix file
λ> ./daemon >[1] "unix:///tmp/syslog.sock"

For safety, there's no eval or string/tilde expansion or command substitution in Nash.

To assign command output to a variable exists the '<=' operator. See the example below:

var fullpath <= realpath $path | xargs -n echo
echo $fullpath

The symbol '<=' redirects the stdout of the command or function invocation in the right-hand side to the variable name specified.

If you want the command output splited into an array, then you'll need to store it in a temporary variable and then use the builtin split function.

var out <= find .
var files <= split($out, "\n")

for f in $files {
        echo "File: " + $f
}

To avoid problems with spaces in variables being passed as multiple arguments to commands, nash pass the contents of each variable as a single argument to the command. It works like enclosing every variable with quotes before executing the command. Then the following example do the right thing:

var fullname = "John Nash"
./ci-register --name $fullname --option somevalue

On bash you need to enclose the $fullname variable in quotes to avoid problems.

Nash syntax does not support shell expansion from strings. There's no way to do things like the following in nash:

echo "The date is: $(date +%D)" # DOESNT WORKS!

Instead you need to assign each command output to a proper variable and then concat it with another string when needed (see the reference docs).

In the same way, nash doesn't support shell expansion at if condition. For check if a directory exists you must use:

-test -d $rootfsDir    # if you forget '-', the script will be aborted here
                       # if path not exists

if $status != "0" {
        echo "RootFS does not exists."
        exit $status
}

Nash stops executing the script at first error found and, in the majority of times, it is what you want (specially for deploys). But Commands have an explicitly way to bypass such restriction by prepending a dash '-' to the command statement. For example:

fn cleanup()
        -rm -rf $buildDir
        -rm -rf $tmpDir
}

The dash '-' works only for operating system commands, other kind of errors are impossible to bypass. For example, trying to evaluate an unbound variable aborts the program with error.

λ> echo $PATH
/bin:/sbin:/usr/bin:/usr/local/bin:/home/user/.local/bin:/home/user/bin:/home/user/.gvm/pkgsets/go1.5.3/global/bin:/home/user/projects/3rdparty/plan9port/bin:/home/user/.gvm/gos/go1.5.3/bin
λ> echo $bleh
ERROR: Variable '$bleh' not set

Long commands can be split in multiple lines:

λ> (aws ec2 attach-internet-gateway	--internet-gateway-id $igwid
									--vpc-id $vpcid)

λ> var instanceId <= (
	aws ec2 run-instances
			--image-id ami-xxxxxxxx
			--count 1
			--instance-type t1.micro
			--key-name MyKeyPair
			--security-groups my-sg
    | jq ".Instances[0].InstanceId"
)
λ> echo $instanceId

Accessing command line args

When you run a nash script like:

λ> nash ./examples/args.sh --arg value

You can get the args using the ARGS variable, that is a list:

#!/usr/bin/env nash

echo "iterating through the arguments list"
echo ""
for arg in $ARGS {
	echo $arg
}

Namespace features

Nash is built with namespace support only on Linux (Plan9 soon). If you use OSX, BSD or Windows, then the rfork keyword will fail.

The examples below assume you are on a Linux box.

Below are some facilities for namespace management inside nash. Make sure you have USER namespaces enabled in your kernel:

zgrep CONFIG_USER_NS /proc/config.gz
CONFIG_USER_NS=y

If it's not enabled you will need root privileges to execute every example below...

Creating a new process in a new USER namespace (u):

λ> id
uid=1000(user) gid=1000(user) groups=1000(user),98(qubes)
λ> rfork u {
     id
}
uid=0(root) gid=0(root) groups=0(root),65534

Yes, Linux supports creation of containers by unprivileged users. Tell this to the customer success of your container-infrastructure-vendor. :-)

The default UID mapping is: Current UID (getuid) => 0 (no range support). I'll look into more options for this in the future.

Yes, you can create multiple nested user namespaces. But kernel limits the number of nested user namespace clones to 32.

λ> rfork u {
    echo "inside first container"

    id

    rfork u {
        echo "inside second namespace..."

        id
    }
}

You can verify that other types of namespace still requires root capabilities, see for PID namespaces (p).

λ> rfork p {
    id
}
ERROR: fork/exec ./nash: operation not permitted

The same happens for mount (m), ipc (i) and uts (s) if used without user namespace (u) flag.

The c flag stands for "container" and is an alias for upmnis (all types of namespaces). If you want another shell (maybe bash) inside the namespace:

λ> rfork c {
    bash
}
[root@stay-away nash]# id
uid=0(root) gid=0(root) groups=0(root),65534
[root@stay-away nash]# mount -t proc proc /proc
[root@stay-away nash]#
[root@stay-away nash]# ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.0  0.0  34648  2748 pts/4    Sl   17:32   0:00 -rcd- -addr /tmp/nash.qNQa.sock
root         5  0.0  0.0  16028  3840 pts/4    S    17:32   0:00 /usr/bin/bash
root        23  0.0  0.0  34436  3056 pts/4    R+   17:34   0:00 ps aux

Everything except the rfork is like a common shell. Rfork will spawn a new process with the namespace flags and executes the commands inside the block on this namespace. It has the form:

rfork <flags> {
    <statements to run inside the container>
}

OK, but how scripts should look like?

See the project nash-app-example.

Didn't work?

I've tested in the following environments:

Linux 4.7-rc7
Archlinux

Linux 4.5.5 (amd64)
Archlinux

Linux 4.3.3 (amd64)
Archlinux

Linux 4.1.13 (amd64)
Fedora release 23

Linux 4.1.13 (amd64)
Debian 8

Language specification

The specification isn't complete yet, but can be found here. The file spec_test.go makes sure it is sane.

Some Bash comparisons

Security

The PID 1 of every namespace created by nash is the same nash binary reading commands from the parent shell via unix socket. It allows the parent namespace (the script that creates the namespace) to issue commands inside the child namespace. In the current implementation the unix socket communication is not secure yet.

Installing libraries

Lets say you have a nash library and you want to install it. For example you have the following:

awesome/code.sh

And you want to install it so you can write code like this:

import awesome/code

code_do_awesome_stuff()

All you have to do is run:

nash -install ./awesome

Or:

nash -install /absolute/path/awesome

The entire awesome dir (and its subdirs) will be copied where nash searches for libraries (dependent on environment variables).

This is the recommended way of installing nash libraries (althought you can do it manually if you want).

Single files can also be installed as packages, for example:

nash -install ./awesome/code.sh

Will enable you to import like this:

import code

If there is already a package with the given name it will be overwritten.

Releasing

To generate a release basically:

• Generate the release on github
• Clone the generated tag
• Run: make release "version=<version>"

Where <version> must match the version of the git tag.

Want to contribute?

Open issues and PR :) The project is in an early stage, be patient because things can change in the future.

"What I cannot create, I do not understand."

-- Richard Feynman