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.Nm 50.Cm disable 51.Ar name 52.Nm 53.Cm enable 54.Ar name 55.Nm 56.Cm list 57.Nm 58.Cm lookup 59.Ar name 60.Nm 61.Cm remove 62.Ar name 63.Sh DESCRIPTION 64The 65.Nm 66utility 67is the management utility for configuring miscellaneous binaries image 68activators in the kernel. 69It allows adding, deleting, disabling, 70enabling, and looking up interpreters. 71Also, all the interpreters can 72be listed. 73.Pp 74The first argument on the command line indicates the operation to be 75performed. 76Operation must be one of the following: 77.Bl -tag -width indent 78.It Xo 79.Cm add 80.Ar name 81.Fl -interpreter 82.Ar path 83.Fl -magic 84.Ar magic 85.Fl -size 86.Ar size 87.Op Fl -mask Ar mask 88.Op Fl -offset Ar offset 89.Op Fl -set-enabled 90.Xc 91Add a new activator entry in the kernel. 92You must specify a 93unique 94.Ar name , 95a 96.Ar path 97to the interpreter, 98header 99.Ar magic 100bytes that uniquely identify a suitable binary for the activator, 101and the 102.Ar size 103of the 104.Ar magic 105in bytes. 106.Pp 107Optionally, you may specify a 108.Ar mask 109to do a bitwise AND with the header bytes. 110This effectively allows you to ignore fields in the binary header that 111do not uniquely indentify the binary file's type. 112.Pp 113An 114.Ar offset 115may be specified for the magic bytes using the 116.Fl -offset 117option. 118By default the 119.Ar offset 120is zero. 121.Pp 122To enable the activator entry the 123.Fl -set-enabled 124option is used. 125The activator default state is disabled. 126.Pp 127The interpreter 128.Ar path 129may also contain arguments for the interpreter including 130.Ar #a 131which gets replaced by the old 132.Dv argv0 133value in the interpreter string. 134.It Cm disable Ar name 135Disable the activator entry identified with 136.Ar name . 137.It Cm enable Ar name 138Enable the activator entry identified with 139.Ar name . 140.It Cm list 141Take a snapshot and print all the activator entries currently configured. 142.It Cm lookup Ar name 143Look up and print out the activator entry identified with 144.Ar name . 145.It Cm remove Ar name 146Remove the activator entry identified with 147.Ar name . 148.El 149.Sh EXAMPLES 150Add an image activator to run the LLVM interpreter 151.Po 152.Xr lli 1 153.Pc 154on bitcode 155compiled files and set its state to enabled. 156In this example 157.Ar #a 158is replaced with the old 159.Dv argv0 160value so that 161.Xr lli 1 162can fake its 163.Dv argv0 : 164.Bd -literal -offset indent 165# binmiscctl add llvmbc --interpreter ''/usr/bin/lli \e 166 --fake-argv0=#a'' --magic ''BC\\xc0\\xde'' --size 4 \e 167 --set-enabled 168.Ed 169.Pp 170Set the state of the 171.Ar llvmbc 172image activator to disabled: 173.Bd -literal -offset indent 174# binmiscctl disable llvmbc 175.Ed 176.Pp 177Set the state of the 178.Ar llvmbc 179image activator to enabled: 180.Bd -literal -offset indent 181# binmiscctl enable llvmbc 182.Ed 183.Pp 184Delete the 185.Ar llvmbc 186image activator: 187.Bd -literal -offset indent 188# binmiscctl remove llvmbc 189.Ed 190.Pp 191Look up and list the record for the 192.Ar llvmbc 193image activator: 194.Bd -literal -offset indent 195# binmiscctl lookup llvmbc 196.Ed 197.Pp 198Add QEMU bsd-user program as an image activator for ARM AARCH64 binaries: 199.Bd -literal -offset indent 200# binmiscctl add arm64 \e 201 --interpreter "/usr/local/bin/qemu-aarch64-static" \e 202 --magic "\ex7f\ex45\ex4c\ex46\ex02\ex01\ex01\ex00\ex00\ex00\e 203 \ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\exb7\ex00" \e 204 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 205 \exff\exff\exff\exff\exff\exff\exfe\exff\exff\exff" \e 206 --size 20 --set-enabled 207.Ed 208.Pp 209Add QEMU bsd-user program as an image activator for ARM little-endian binaries: 210.Bd -literal -offset indent 211# binmiscctl add armelf \e 212 --interpreter "/usr/local/bin/qemu-arm-static" \e 213 --magic "\ex7f\ex45\ex4c\ex46\ex01\ex01\ex01\ex00\ex00\ex00\e 214 \ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex28\ex00" \e 215 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 216 \exff\exff\exff\exff\exff\exff\exfe\exff\exff\exff" \e 217 --size 20 --set-enabled 218.Ed 219.Pp 220Add QEMU bsd-user program as an image activator for ARM big-endian binaries: 221.Bd -literal -offset indent 222# binmiscctl add armebelf \e 223 --interpreter "/usr/local/bin/qemu-arm-static" \e 224 --magic "\ex7f\ex45\ex4c\ex46\ex01\ex02\ex01\ex00\ex00\ex00\e 225 \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex28" \e 226 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 227 \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e 228 --size 20 --set-enabled 229.Ed 230.Pp 231Add QEMU bsd-user program as an image activator for MIPS32 binaries: 232.Bd -literal -offset indent 233# binmiscctl add mips32 \e 234 --interpreter "/usr/local/bin/qemu-mips-static" \e 235 --magic "\ex7f\ex45\ex4c\ex46\ex01\ex02\ex01\ex00\ex00\ex00\e 236 \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex08" \e 237 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 238 \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e 239 --size 20 --set-enabled 240.Ed 241.Pp 242Add QEMU bsd-user program as an image activator for MIPS64 binaries: 243.Bd -literal -offset indent 244# binmiscctl add mips64 \e 245 --interpreter "/usr/local/bin/qemu-mips64-static" \e 246 --magic "\ex7f\ex45\ex4c\ex46\ex02\ex02\ex01\ex00\ex00\ex00\e 247 \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex08" \e 248 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 249 \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e 250 --size 20 --set-enabled 251.Ed 252.Pp 253Add QEMU bsd-user program as an image activator for PowerPC binaries: 254.Bd -literal -offset indent 255# binmiscctl add powerpc \e 256 --interpreter "/usr/local/bin/qemu-ppc-static" \e 257 --magic "\ex7f\ex45\ex4c\ex46\ex01\ex02\ex01\ex00\ex00\ex00\e 258 \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex14" \e 259 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 260 \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e 261 --size 20 --set-enabled 262.Ed 263.Pp 264Add QEMU bsd-user program as an image activator for PowerPC64 binaries: 265.Bd -literal -offset indent 266# binmiscctl add powerpc64 \e 267 --interpreter "/usr/local/bin/qemu-ppc64-static" \e 268 --magic "\ex7f\ex45\ex4c\ex46\ex02\ex02\ex01\ex00\ex00\ex00\e 269 \ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex15" \e 270 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 271 \exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e 272 --size 20 --set-enabled 273.Ed 274.Pp 275Add QEMU bsd-user program as an image activator for 64-bit RISC-V binaries: 276.Bd -literal -offset indent 277# binmiscctl add riscv64 \e 278 --interpreter "/usr/local/bin/qemu-riscv64-static" \e 279 --magic "\ex7f\ex45\ex4c\ex46\ex02\ex01\ex01\ex00\ex00\ex00\e 280 \ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\exf3\ex00" \e 281 --mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e 282 \exff\exff\exff\exff\exff\exff\exfe\exff\exff\exff" \e 283 --size 20 --set-enabled 284.Ed 285.Ss "Create and use an ARMv6 chroot on an AMD64 host" 286Use an existing source tree to build a chroot host with architecture 287overrides: 288.Bd -literal -offset ident 289D=/path/to/chroot 290cd /usr/src 291mkdir -p $D 292make world TARGET=arm TARGET_ARCH=armv6 DESTDIR=$D 293make distribution TARGET=arm TARGET_ARCH=armv6 DESTDIR=$D 294.Ed 295.Pp 296With 297.Pa emulators/qemu-user-static 298from the 299.Fx 300Ports Collection, the emulator must be copied into the jail path 301specified in the 302.Nm 303command. 304Using the example above: 305.Bd -literal -offset -ident 306mkdir $D/usr/local/bin 307cp /usr/local/bin/qemu-arm-static $D/usr/local/bin 308.Ed 309.Pp 310Now the user can chroot into the environment normally, as root: 311.Bd -literal -offset -ident 312chroot $D 313.Ed 314.Sh SEE ALSO 315.Xr lli 1 , 316.Xr execve 2 , 317.Xr jail 8 318.Sh HISTORY 319The 320.Nm 321command was added in 322.Fx 10.1 . 323It was developed to support the imgact_binmisc kernel module. 324.Sh AUTHORS 325.An Stacey D Son Aq Mt sson@FreeBSD.org 326