Release Notes

busybox-w32 version FRP-5007-g82accfc19 was released on 2023-05-28. It is no longer current. For other release notes see:

Dropping elevated privileges

Suppose you've configured OpenSSH for Windows to use the busybox-w32 shell. When you log in you'll see something like this:
~ $ ssh rmy@localhost
rmy@localhost's password:
~ # id
uid=0(root) gid=0(root) groups=0(root)
~ #

The ~ #  prompt and the output of id indicate we're running as root.

As with many things related to ownership and permissions this isn't entirely true. busybox-w32 tries to relate what's actually happening on Windows to how things might be expected to work on Unix. In fact, we're running as rmy but with elevated privileges.

Normally when elevated privileges are required for an operation Windows displays a User Access Control (UAC) prompt. The Microsoft OpenSSH developers couldn't think of a way to do this remotely, so they made the design decision that any user who is an administrator would be given elevated privileges when they logged in.

This is fine if you need to do things that require elevated privileges, but that isn't always the case: some things are best done without elevated privileges.

They've thus replaced one problem (not being able to raise privilege when working remotely) with a different one (not being able to drop privilege if we want to run as a normal user).

The new drop applet makes it possible to drop elevated privileges. Without any arguments it starts an interactive, unprivileged shell:

~ # drop
~ $ id
uid=4095(rmy) gid=4095(rmy) groups=4095(rmy)
~ $

It can also be used to run a single command without privilege:

~ # drop -c 'id -un'
rmy
~ # drop -- id -un
rmy
~ #
To drop privilege for the rest of the remote session use:
~ # exec drop
~ $

The cdrop and pdrop applets are similar but use cmd.exe and PowerShell instead of the busybox-w32 shell.

The mechanism used to drop privilege results in a state that's almost, but not quite, exactly like being unprivileged. In some cases applications may, incorrectly, think they're running with privileges. If they try to perform a privileged operation, though, it should fail.

(GitHub issue #240)

su applet

The su applet has been updated so its arguments more closely match those on Unix. As well as the -c option it also now supports passing arbitrary options and arguments to the shell. To conform to the Unix command line layout this requires a username to be supplied, which must be root.

The usage may be summarised as:

   su [options] -c CMD_STRING [[--] root [ARG0 [ARG...]]]
   su [options] [[--] root [arbitrary shell arguments]]

Note:

The new shell started by su appears in a separate window, unlike on Unix where the shell reuses the same terminal. Two non-standard options have been added to assist in dealing with this different behaviour.

(GitHub issue #314, PR #317)

Signals, kill and trap

Microsoft Windows has very limited support for signals. The C runtime only acknowledges the six signals required by the standard: ABRT, FPE, ILL, INT, SEGV and TERM. While the operating system may raise some of these signals it doesn't allow programs to send them. The mechanism used to interrupt programs with Ctrl-C is entirely distinct from the INT signal.

Much of the support for signals in busybox-w32 therefore has to be implemented from scratch. There are some limitations:

There have been some recent changes in this area:

Terminal modes

The environment variable BB_SKIP_ANSI_EMULATION was introduced in FRP-3466 to control the output of ANSI escape sequences. They could either be emulated using the console API or output verbatim to terminals that supported them.

The Windows Terminal can also support virtual terminal (VT) sequences on input. This more closely matches how things like cursor keys are handled on Unix. In contrast, busybox-w32 has previously always used the Windows console API for this purpose.

In this release support for VT input has been enabled. This means busybox-w32 can now handle all I/O modes available in the Windows Terminal and Windows Console applications.

The environment variable BB_TERMINAL_MODE controls the input and output modes of the terminal. The allowed values are integers from 0 to 5 with the behaviour described in the key below:

Mode  | Input  | Output
-----------------------
  0   |   C    |    C
  1   |   C    |    V
  2   |   V    |    C
  3   |   V    |    V
  4   |   D    |    D
  5   |   D    |    V

The default value is 5, which should work well in most cases. Values 0-3 are probably only useful for testing as they may result in incorrect behaviour.

BB_SKIP_ANSI_EMULATION is still supported, though it may be removed in future. If both variables are set BB_TERMINAL_MODE takes precedence over BB_SKIP_ANSI_EMULATION.

Bug fixes and enhancements

Changes imported from upstream

busybox-w32 has been synchronised with upstream BusyBox. As a result the following bug fixes and enhancements are available (among others):