Differential D15589 Diff 45633 head/usr.sbin/binmiscctl/binmiscctl.8

Changeset View

Standalone View

head/usr.sbin/binmiscctl/binmiscctl.8

	Show All 21 Lines
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.\" Support for miscellaneous binary image activators			.\" Support for miscellaneous binary image activators
	.\"			.\"
	.Dd December 30, 2014			.Dd July 21, 2018
	.Dt BINMISCCTL 8			.Dt BINMISCCTL 8
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm binmiscctl			.Nm binmiscctl
	.Nd manage binary image activators			.Nd manage binary image activators
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.Nm			.Nm
	.Cm add			.Cm add
	.Ar name			.Ar name
	.Cm --interpreter			.Fl -interpreter
	.Ar path			.Ar path
	.Cm --magic			.Fl -magic
	.Ar magic			.Ar magic
	.Cm --size			.Fl -size
	.Ar size			.Ar size
	.Op Cm --mask Ar mask			.Op Fl -mask Ar mask
	.Op Cm --offset Ar offset			.Op Fl -offset Ar offset
	.Op Cm --set-enabled			.Op Fl -set-enabled
	.Nm			.Nm
	.Cm remove
	.Ar name
	.Nm
	.Cm disable			.Cm disable
	.Ar name			.Ar name
	.Nm			.Nm
	.Cm enable			.Cm enable
	.Ar name			.Ar name
	.Nm			.Nm
				.Cm list
				.Nm
	.Cm lookup			.Cm lookup
	.Ar name			.Ar name
	.Nm			.Nm
	.Cm list			.Cm remove
				.Ar name
	.Sh DESCRIPTION			.Sh DESCRIPTION
	The			The
	.Nm			.Nm
	utility			utility
	is the management utility for configuring miscellaneous binaries image			is the management utility for configuring miscellaneous binaries image
	activators in the kernel.			activators in the kernel.
	It allows adding, deleting, disabling,			It allows adding, deleting, disabling,
	enabling, and looking up interpreters.			enabling, and looking up interpreters.
	Also, all the interpreters can			Also, all the interpreters can
	be listed.			be listed.
	.Pp			.Pp
	The first argument on the command line indicates the operation to be			The first argument on the command line indicates the operation to be
	performed.			performed.
	Operation must be one of the following:			Operation must be one of the following:
	.Bl -tag -width indent			.Bl -tag -width indent
	.It Xo			.It Xo
	.Cm add			.Cm add
	.Ar name			.Ar name
	.Cm --interpreter			.Fl -interpreter
	.Ar path			.Ar path
	.Cm --magic			.Fl -magic
	.Ar magic			.Ar magic
	.Cm --size			.Fl -size
	.Ar size			.Ar size
	.Op Cm --mask Ar mask			.Op Fl -mask Ar mask
	.Op Cm --offset Ar offset			.Op Fl -offset Ar offset
	.Op Cm --set-enabled			.Op Fl -set-enabled
	.Xc			.Xc
	Add a new activator entry in the kernel.			Add a new activator entry in the kernel.
	You must specify a			You must specify a
	unique			unique
	.Ar name,			.Ar name ,
	interpreter path and its arguments			a
	.Ar path,			.Ar path
				to the interpreter,
	header			header
	.Ar magic			.Ar magic
	bytes that uniquely identify a suitable binary for the activator,			bytes that uniquely identify a suitable binary for the activator,
	and the			and the
	.Ar size			.Ar size
	of the			of the
	.Ar magic			.Ar magic
	in bytes.			in bytes.
	.Pp			.Pp
	Optionally you may specify a			Optionally, you may specify a
	.Ar mask			.Ar mask
	to do a bitwise AND with the header bytes.			to do a bitwise AND with the header bytes.
	This effectively allows you to ignore fields in the binary header that			This effectively allows you to ignore fields in the binary header that
	do not uniquely indentify the binary file's type.			do not uniquely indentify the binary file's type.
	.Pp			.Pp
	An			An
	.Ar offset			.Ar offset
	may be specified for the magic bytes using the			may be specified for the magic bytes using the
	.Cm --offset			.Fl -offset
	option.			option.
	By default the			By default the
	.Ar offset			.Ar offset
	is zero.			is zero.
	.Pp			.Pp
	To enable the activator entry the			To enable the activator entry the
	.Cm --set-enabled			.Fl -set-enabled
	option is used.			option is used.
	The activator default state is disabled.			The activator default state is disabled.
	.Pp			.Pp
	The interpreter			The interpreter
	.Ar path			.Ar path
	may also contain arguments for the interpreter including			may also contain arguments for the interpreter including
	.Ar #a			.Ar #a
	which gets replaced by the old			which gets replaced by the old
	.Dv argv0			.Dv argv0
	value in the interpreter string.			value in the interpreter string.
	.It Cm remove Ar name
	Remove the activator entry identified with
	.Ar name .
	.It Cm disable Ar name			.It Cm disable Ar name
	Disable the activator entry identified with			Disable the activator entry identified with
	.Ar name .			.Ar name .
	.It Cm enable Ar name			.It Cm enable Ar name
	Enable the activator entry identified with			Enable the activator entry identified with
	.Ar name .			.Ar name .
				.It Cm list
				Take a snapshot and print all the activator entries currently configured.
	.It Cm lookup Ar name			.It Cm lookup Ar name
	Look up and print out the activator entry identified with			Look up and print out the activator entry identified with
	.Ar name .			.Ar name .
	.It Cm list			.It Cm remove Ar name
	Take a snapshot and print all the activator entries currently configured.			Remove the activator entry identified with
				.Ar name .
	.El			.El
	.Sh EXAMPLES			.Sh EXAMPLES
	Add an image activator to run the LLVM interpreter (lli) on bitcode			Add an image activator to run the LLVM interpreter
	compiled files:			.Po
	.Bd -ragged -offset indent			.Xr lli 1
	# binmiscctl add llvmbc --interpreter ''/usr/bin/lli --fake-argv0=#a''			.Pc
	--magic ''BC\\xc0\\xde'' --size 4 --set-enabled			on bitcode
	.Ed			compiled files and set its state to enabled.
	.Pp			In this example
	.Ar #a			.Ar #a
	is replaced with the old			is replaced with the old
	.Dv argv0			.Dv argv0
	value so that 'lli' can fake its			value so that
	.Dv argv0 .			.Xr lli 1
	Set its state to enabled.			can fake its
				.Dv argv0 :
				.Bd -literal -offset indent
				# binmiscctl add llvmbc --interpreter ''/usr/bin/lli \e
				--fake-argv0=#a'' --magic ''BC\\xc0\\xde'' --size 4 \e
				--set-enabled
				.Ed
	.Pp			.Pp
	Set the state of the			Set the state of the
	.Ar llvmbc			.Ar llvmbc
	image activator to disabled:			image activator to disabled:
	.Dl # binmiscctl disable llvmbc			.Bd -literal -offset indent
				# binmiscctl disable llvmbc
				.Ed
	.Pp			.Pp
	Set the state of the			Set the state of the
	.Ar llvmbc			.Ar llvmbc
	image activator to enabled:			image activator to enabled:
	.Dl # binmiscctl enable llvmbc			.Bd -literal -offset indent
				# binmiscctl enable llvmbc
				.Ed
	.Pp			.Pp
	Delete the			Delete the
	.Ar llvmbc			.Ar llvmbc
	image activator:			image activator:
	.Dl # binmiscctl remove llvmbc			.Bd -literal -offset indent
				# binmiscctl remove llvmbc
				.Ed
	.Pp			.Pp
	Look up and list the record for the			Look up and list the record for the
	.Ar llvmbc			.Ar llvmbc
	image activator:			image activator:
	.Dl # binmiscctl lookup llvmbc			.Bd -literal -offset indent
				# binmiscctl lookup llvmbc
				.Ed
	.Pp			.Pp
	Add QEMU bsd-user program as an image activator for ARM AARCH64 binaries:			Add QEMU bsd-user program as an image activator for ARM AARCH64 binaries:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	# binmiscctl add arm64 \e			# binmiscctl add arm64 \e
	--interpreter "/usr/local/bin/qemu-aarch64-static" \e			--interpreter "/usr/local/bin/qemu-aarch64-static" \e
	--magic "\ex7f\ex45\ex4c\ex46\ex02\ex01\ex01\ex00\ex00\ex00\e			--magic "\ex7f\ex45\ex4c\ex46\ex02\ex01\ex01\ex00\ex00\ex00\e
	\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\exb7\ex00" \e			\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\exb7\ex00" \e
	--mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e			--mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e
	▲ Show 20 Lines • Show All 72 Lines • ▼ Show 20 Lines
	# binmiscctl add sparc64 \e			# binmiscctl add sparc64 \e
	--interpreter "/usr/local/bin/qemu-sparc64-static" \e			--interpreter "/usr/local/bin/qemu-sparc64-static" \e
	--magic "\ex7f\ex45\ex4c\ex46\ex02\ex02\ex01\ex00\ex00\ex00\e			--magic "\ex7f\ex45\ex4c\ex46\ex02\ex02\ex01\ex00\ex00\ex00\e
	\ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex2b" \e			\ex00\ex00\ex00\ex00\ex00\ex00\ex00\ex02\ex00\ex2b" \e
	--mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e			--mask "\exff\exff\exff\exff\exff\exff\exff\ex00\exff\exff\e
	\exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e			\exff\exff\exff\exff\exff\exff\exff\exfe\exff\exff" \e
	--size 20 --set-enabled			--size 20 --set-enabled
	.Ed			.Ed
	.Pp
	.Ss "Create and use an ARMv6 chroot on an AMD64 host"			.Ss "Create and use an ARMv6 chroot on an AMD64 host"
	Use an existing source tree to build a chroot host with architecture			Use an existing source tree to build a chroot host with architecture
	overrides:			overrides:
	.Bd -literal			.Bd -literal -offset ident
	D=/path/to/chroot			D=/path/to/chroot
	cd /usr/src			cd /usr/src
	mkdir -p $D			mkdir -p $D
	make world TARGET=arm TARGET_ARCH=armv6 DESTDIR=$D			make world TARGET=arm TARGET_ARCH=armv6 DESTDIR=$D
	make distribution TARGET=arm TARGET_ARCH=armv6 DESTDIR=$D			make distribution TARGET=arm TARGET_ARCH=armv6 DESTDIR=$D
	.Ed			.Ed
	.Pp			.Pp
	With			With
	.Pa emulators/qemu-user-static			.Pa emulators/qemu-user-static
	from the			from the
	.Fx			.Fx
	Ports Collection, the emulator must be copied into the jail path			Ports Collection, the emulator must be copied into the jail path
	specified in the binmiscctl command.			specified in the
				.Nm
				command.
	Using the example above:			Using the example above:
	.Bd -literal			.Bd -literal -offset -ident
	mkdir $D/usr/local/bin			mkdir $D/usr/local/bin
	cp /usr/local/bin/qemu-arm-static $D/usr/local/bin			cp /usr/local/bin/qemu-arm-static $D/usr/local/bin
	.Ed			.Ed
	.Pp			.Pp
	Now the user can chroot into the environment normally, as root:			Now the user can chroot into the environment normally, as root:
	.Bd -literal			.Bd -literal -offset -ident
	chroot $D			chroot $D
	.Ed			.Ed
	.Sh SEE ALSO			.Sh SEE ALSO
	.Xr lli 1 ,			.Xr lli 1 ,
	.Xr execve 2 ,			.Xr execve 2 ,
	.Xr jail 8			.Xr jail 8
	.Sh HISTORY			.Sh HISTORY
	The			The
	.Cm binmiscctl			.Nm
	command was added in			command was added in
	.Fx 10.1 .			.Fx 10.1 .
	It was developed to support the imgact_binmisc kernel module.			It was developed to support the imgact_binmisc kernel module.
	.Sh AUTHORS			.Sh AUTHORS
	Stacey D Son			.An Stacey D Son Aq Mt sson@FreeBSD.org