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 10, 2014 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.Cm --interpreter 41.Ar path 42.Cm --magic 43.Ar magic 44.Cm --size 45.Ar size 46.Op Cm --mask Ar mask 47.Op Cm --offset Ar offset 48.Op Cm --set-enabled 49.Nm 50.Cm remove 51.Ar name 52.Nm 53.Cm disable 54.Ar name 55.Nm 56.Cm enable 57.Ar name 58.Nm 59.Cm lookup 60.Ar name 61.Nm 62.Cm list 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.Cm --interpreter 82.Ar path 83.Cm --magic 84.Ar magic 85.Cm --size 86.Ar size 87.Op Cm --mask Ar mask 88.Op Cm --offset Ar offset 89.Op Cm --set-enabled 90.Xc 91Add a new activator entry in the kernel. 92You must specify a 93unique 94.Ar name, 95interpreter path and its arguments 96.Ar path, 97header 98.Ar magic 99bytes that uniquely identify a suitable binary for the activator, 100and the 101.Ar size 102of the 103.Ar magic 104in bytes. 105.Pp 106Optionally you may specify a 107.Ar mask 108to do a bitwise AND with the header bytes. 109This effectively allows you to ignore fields in the binary header that 110do not uniquely indentify the binary file's type. 111.Pp 112An 113.Ar offset 114may be specified for the magic bytes using the 115.Cm --offset 116option. 117By default the 118.Ar offset 119is zero. 120.Pp 121To enable the activator entry the 122.Cm --set-enabled 123option is used. 124The activator default state is disabled. 125.Pp 126The interpreter 127.Ar path 128may also contain arguments for the interpreter including 129.Ar #a 130which gets replaced by the old 131.Dv argv0 132value in the interpreter string. 133.It Cm remove Ar name 134Remove the activator entry identified with 135.Ar name . 136.It Cm disable Ar name 137Disable the activator entry identified with 138.Ar name . 139.It Cm enable Ar name 140Enable the activator entry identified with 141.Ar name . 142.It Cm lookup Ar name 143Look up and print out the activator entry identified with 144.Ar name . 145.It Cm list 146Take a snapshot and print all the activator entries currently configured. 147.El 148.Sh EXAMPLES 149.Bd -ragged -offset indent 150# binmiscctl add llvmbc --interpreter ''/usr/bin/lli --fake-argv0=#a'' 151--magic ''BC\\xc0\\xde'' --size 4 --set-enabled 152.Ed 153.Pp 154Add an image activator to run the LLVM interpreter (lli) on bitcode 155compiled files. 156.Ar #a 157gets replaced with the old 158.Dv argv0 159value so that 'lli' can fake its 160.Dv argv0 . 161Set its state to enabled. 162.Pp 163.Dl # binmiscctl disable llvmbc 164.Pp 165Set the state of the 166.Ar llvmbc 167image activator to disabled. 168.Pp 169.Dl # binmiscctl enable llvmbc 170.Pp 171Set the state of the 172.Ar llvmbc 173image activator to enabled. 174.Pp 175.Dl # binmiscctl remove llvmbc 176.Pp 177Delete the 178.Ar llvmbc 179image activator. 180.Pp 181.Dl # binmiscctl lookup llvmbc 182.Pp 183Look up and list the record for the 184.Ar llvmbc 185image activator. 186.Sh SEE ALSO 187.Xr lli 1 , 188.Xr execve 2 189.Sh HISTORY 190The 191.Cm binmiscctl 192command was added in 193.Fx 10.1 . 194It was developed to support the imgact_binmisc kernel module. 195.Sh AUTHORS 196Stacey D Son 197