1.\"- 2.\" Copyright (c) 2013 Stacey D. Son 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.\" Support for miscellaneous binary image activators 29.\" 30.Dd April 30, 2020 31.Dt BINMISCCTL 8 32.Os 33.Sh NAME 34.Nm binmiscctl 35.Nd manage binary image activators 36.Sh SYNOPSIS 37.Nm 38.Cm add 39.Ar name 40.Fl -interpreter 41.Ar path 42.Fl -magic 43.Ar magic 44.Fl -size 45.Ar size 46.Op Fl -mask Ar mask 47.Op Fl -offset Ar offset 48.Op Fl -set-enabled 49.Op Fl -pre-open 50.Nm 51.Cm disable 52.Ar name 53.Nm 54.Cm enable 55.Ar name 56.Nm 57.Cm list 58.Nm 59.Cm lookup 60.Ar name 61.Nm 62.Cm remove 63.Ar name 64.Sh DESCRIPTION 65The 66.Nm 67utility 68is the management utility for configuring miscellaneous binaries image 69activators in the kernel. 70It allows adding, deleting, disabling, 71enabling, and looking up interpreters. 72Also, all the interpreters can 73be listed. 74.Pp 75The first argument on the command line indicates the operation to be 76performed. 77Operation must be one of the following: 78.Bl -tag -width indent 79.It Xo 80.Cm add 81.Ar name 82.Fl -interpreter 83.Ar path 84.Fl -magic 85.Ar magic 86.Fl -size 87.Ar size 88.Op Fl -mask Ar mask 89.Op Fl -offset Ar offset 90.Op Fl -set-enabled 91.Op Fl -pre-open 92.Xc 93Add a new activator entry in the kernel. 94You must specify a 95unique 96.Ar name , 97a 98.Ar path 99to the interpreter, 100header 101.Ar magic 102bytes that uniquely identify a suitable binary for the activator, 103and the 104.Ar size 105of the 106.Ar magic 107in bytes. 108.Pp 109Optionally, you may specify a 110.Ar mask 111to do a bitwise AND with the header bytes. 112This effectively allows you to ignore fields in the binary header that 113do not uniquely indentify the binary file's type. 114.Pp 115An 116.Ar offset 117may be specified for the magic bytes using the 118.Fl -offset 119option. 120By default the 121.Ar offset 122is zero. 123.Pp 124To enable the activator entry the 125.Fl -set-enabled 126option is used. 127The activator default state is disabled. 128.Pp 129To make the interpreter automatically available in jails and chroots, 130use the 131.Fl -pre-open 132option to allow the kernel to open the binary at configuration time 133rather then lazily when the the interpreted program is started. 134.Pp 135The interpreter 136.Ar path 137may also contain arguments for the interpreter including 138.Ar #a 139which gets replaced by the old 140.Dv argv0 141value in the interpreter string. 142.It Cm disable Ar name 143Disable the activator entry identified with 144.Ar name . 145.It Cm enable Ar name 146Enable the activator entry identified with 147.Ar name . 148.It Cm list 149Take a snapshot and print all the activator entries currently configured. 150.It Cm lookup Ar name 151Look up and print out the activator entry identified with 152.Ar name . 153.It Cm remove Ar name 154Remove the activator entry identified with 155.Ar name . 156.El 157.Sh EXAMPLES 158Add an image activator to run the LLVM interpreter 159.Po 160.Xr lli 1 161.Pc 162on bitcode 163compiled files and set its state to enabled. 164In this example 165.Ar #a 166is replaced with the old 167.Dv argv0 168value so that 169.Xr lli 1 170can fake its 171.Dv argv0 : 172.Bd -literal -offset indent 173# binmiscctl add llvmbc --interpreter ''/usr/bin/lli \e 174 --fake-argv0=#a'' --magic ''BC\\xc0\\xde'' --size 4 \e 175 --set-enabled 176.Ed 177.Pp 178Set the state of the 179.Ar llvmbc 180image activator to disabled: 181.Bd -literal -offset indent 182# binmiscctl disable llvmbc 183.Ed 184.Pp 185Set the state of the 186.Ar llvmbc 187image activator to enabled: 188.Bd -literal -offset indent 189# binmiscctl enable llvmbc 190.Ed 191.Pp 192Delete the 193.Ar llvmbc 194image activator: 195.Bd -literal -offset indent 196# binmiscctl remove llvmbc 197.Ed 198.Pp 199Look up and list the record for the 200.Ar llvmbc 201image activator: 202.Bd -literal -offset indent 203# binmiscctl lookup llvmbc 204.Ed 205.Pp 206Add QEMU bsd-user program as an image activator for ARM AARCH64 binaries: 207.Bd -literal -offset indent 208# binmiscctl add arm64 \e 209 --interpreter "/usr/local/bin/qemu-aarch64-static" \e 210 --magic "\ex7f\ex45\ex4c\ex46\ex02\ex01\ex01\ex00\ex00\ex00\e 211 \ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\exb7\ex00" \e 212 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 213 \exff\exff\exff\exff\exff\exff\exfe\exff\exff\exff" \e 214 --size 20 --set-enabled 215.Ed 216.Pp 217Add QEMU bsd-user program as an image activator for ARM little-endian binaries: 218.Bd -literal -offset indent 219# binmiscctl add armelf \e 220 --interpreter "/usr/local/bin/qemu-arm-static" \e 221 --magic "\ex7f\ex45\ex4c\ex46\ex01\ex01\ex01\ex00\ex00\ex00\e 222 \ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex28\ex00" \e 223 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 224 \exff\exff\exff\exff\exff\exff\exfe\exff\exff\exff" \e 225 --size 20 --set-enabled 226.Ed 227.Pp 228Add QEMU bsd-user program as an image activator for ARM big-endian binaries: 229.Bd -literal -offset indent 230# binmiscctl add armebelf \e 231 --interpreter "/usr/local/bin/qemu-arm-static" \e 232 --magic "\ex7f\ex45\ex4c\ex46\ex01\ex02\ex01\ex00\ex00\ex00\e 233 \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex28" \e 234 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 235 \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e 236 --size 20 --set-enabled 237.Ed 238.Pp 239Add QEMU bsd-user program as an image activator for MIPS32 binaries: 240.Bd -literal -offset indent 241# binmiscctl add mips32 \e 242 --interpreter "/usr/local/bin/qemu-mips-static" \e 243 --magic "\ex7f\ex45\ex4c\ex46\ex01\ex02\ex01\ex00\ex00\ex00\e 244 \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex08" \e 245 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 246 \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e 247 --size 20 --set-enabled 248.Ed 249.Pp 250Add QEMU bsd-user program as an image activator for MIPS64 binaries: 251.Bd -literal -offset indent 252# binmiscctl add mips64 \e 253 --interpreter "/usr/local/bin/qemu-mips64-static" \e 254 --magic "\ex7f\ex45\ex4c\ex46\ex02\ex02\ex01\ex00\ex00\ex00\e 255 \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex08" \e 256 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 257 \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e 258 --size 20 --set-enabled 259.Ed 260.Pp 261Add QEMU bsd-user program as an image activator for PowerPC binaries: 262.Bd -literal -offset indent 263# binmiscctl add powerpc \e 264 --interpreter "/usr/local/bin/qemu-ppc-static" \e 265 --magic "\ex7f\ex45\ex4c\ex46\ex01\ex02\ex01\ex00\ex00\ex00\e 266 \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex14" \e 267 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 268 \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e 269 --size 20 --set-enabled 270.Ed 271.Pp 272Add QEMU bsd-user program as an image activator for PowerPC64 binaries: 273.Bd -literal -offset indent 274# binmiscctl add powerpc64 \e 275 --interpreter "/usr/local/bin/qemu-ppc64-static" \e 276 --magic "\ex7f\ex45\ex4c\ex46\ex02\ex02\ex01\ex00\ex00\ex00\e 277 \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex15" \e 278 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 279 \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e 280 --size 20 --set-enabled 281.Ed 282.Pp 283Add QEMU bsd-user program as an image activator for 64-bit RISC-V binaries: 284.Bd -literal -offset indent 285# binmiscctl add riscv64 \e 286 --interpreter "/usr/local/bin/qemu-riscv64-static" \e 287 --magic "\ex7f\ex45\ex4c\ex46\ex02\ex01\ex01\ex00\ex00\ex00\e 288 \ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\exf3\ex00" \e 289 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 290 \exff\exff\exff\exff\exff\exff\exfe\exff\exff\exff" \e 291 --size 20 --set-enabled 292.Ed 293.Ss "Create and use an ARMv6 chroot on an AMD64 host" 294Use an existing source tree to build a chroot host with architecture 295overrides: 296.Bd -literal -offset ident 297D=/path/to/chroot 298cd /usr/src 299mkdir -p $D 300make world TARGET=arm TARGET_ARCH=armv6 DESTDIR=$D 301make distribution TARGET=arm TARGET_ARCH=armv6 DESTDIR=$D 302.Ed 303.Pp 304With 305.Pa emulators/qemu-user-static 306from the 307.Fx 308Ports Collection, the emulator must be copied into the jail path 309specified in the 310.Nm 311command. 312Using the example above: 313.Bd -literal -offset -ident 314mkdir $D/usr/local/bin 315cp /usr/local/bin/qemu-arm-static $D/usr/local/bin 316.Ed 317.Pp 318Now the user can chroot into the environment normally, as root: 319.Bd -literal -offset -ident 320chroot $D 321.Ed 322.Sh SEE ALSO 323.Xr lli 1 , 324.Xr execve 2 , 325.Xr jail 8 326.Sh HISTORY 327The 328.Nm 329command was added in 330.Fx 10.1 . 331It was developed to support the imgact_binmisc kernel module. 332.Sh AUTHORS 333.An Stacey D Son Aq Mt sson@FreeBSD.org 334