Copyright (c) 2011 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Tohru Nishimura.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT 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 SUCH DAMAGE.
.Dd October 7, 2013 .Dt ALTBOOT 8 sandpoint .Os .Sh NAME .Nm altboot .Nd program to boot .Nx kernel from disk or network .Sh DESCRIPTION .Nm is a standalone program which works on top of a .Tn NAS product's bootloader. It is capable of loading a .Nx kernel from an .Tn IDE or .Tn SATA disk drive, or via network with .Tn NFS or .Tn TFTP protocol. .Nm can be stored in flash ROM. Typically you will first copy it from flash into RAM and then invoke it there to boot the .Nx kernel.
p .Nm runs in conjunction with popular .Tn U-Boot/PPCBoot bootloaders used by .Tn NAS products. With an appropriate boot command line, saved in the environment, .Nm can load and start a .Nx kernel without manual intervention. The original .Tn U-Boot/PPCBoot bootloaders remain useful and altboot works as a functional extension of them. .Sh EXAMPLES .Nm occupies less than 128KB in volume and can be stored to any vacant space of the system's flash. It is made to run at RAM address offset 0x0100'0000. .Tn U-Boot/PPCboot is instructed to copy the program to RAM in this way:
p .Dl => cp.b fffe0000 1000000 20000
p Here 0xfffe'0000 is the flash address where .Nm is stored while 0x0100'0000 is the RAM address to copy to.
p The invocation syntax is:
p .Dl => go 1000000 Ar ide:N Ar opt1 Ar opt2 ... Ar bootname l -tag -width xx t Va ide:N where .Ar N is a string of digits, which defines the number of connected drives on each PATA channel. This option is useful to avoid the delays, when .Nm is trying to detect a non-existing drive. Examples: l -tag -width xx t ide: Ns Ar 10 A single master drive on the first channel. Nothing on the second channel. t ide: Ns Ar 22 A master and slave drive on both channels of the first controller. t ide: Ns Ar 1111 A master drive on each channel. The first two digits belong to the first controller, the last two to the second controller. .El
p Unspecified digits will be read as .Ar 0 . The .Ar ide option has only a meaning for PATA disks. Omitting it makes it default to .Ar ide:10 .
p t Va optN multi, auto, ask, single, ddb, userconf, norm, quiet, verb, silent, debug
p Omitting optN makes .Nm default to multi-user mode boot.
p N.B., the maximum number of allowed go command arguments varies and depends on the .Tn U-Boot/PPCBoot buildtime configuration. t Va bootname One of the following:
p .Dl nfs: Ns Ar filename .Dl nfs: .Dl tftp: Ns Ar filename .Dl tftp: .Dl wd Ns Ar Np : Ns Ar filename .Dl wd Ns Ar Np : .Dl mem: Ns Ar address .Dl net:
p The last one is a synonym for .Dq nfs . t nfs: Ns Va filename issue a .Tn DHCP request to determine the .Tn IP address and download .Ar filename from the .Tn NFS server. t nfs: target file is determined by .Sy filename field of
a /etc/dhcpd.conf t tftp: Ns Va filename issue a .Tn DHCP request to determine .Tn IP address and download .Ar filename from the .Tn TFTP server. t tftp: target file is determined by .Sy filename field of
a /etc/dhcpd.conf t wd Ns Va Np : Ns Va filename load the .Tn ELF .Nx kernel .Ar filename from an .Tn FFSv2 or .Tn FFSv1 filesystem. .Ar N is a number to distinguish the target drive. .Ar p is a partition specifier. When omitted, partition .Sq a is assumed. .Dq wd0a means partition .Sq a of the first disk drive. t wd Ns Va Np : use filename .Dq netbsd for booting the .Tn ELF .Nx kernel. t mem: Ns Va address boots the .Tn ELF .Nx kernel from any address in memory. The .Ar address argument has to be specified as a hexadecimal number and denotes the start address of the .Tn ELF image in memory. .El
p .Nm can boot from RAID 1 partitions, but only if the RAID partition is the first partition on the disk.
p .Tn U-Boot/PPCBoot provides a way to run a short list of commands right after power-on. The following is a procedure to setup the system for starting .Nx after a 5 second delay, allowing the user to break into interactive mode. Note that a backslashed .Sq ; is necessary to enter the script correctly. d -literal -offset indent => setenv bootcmd cp.b fffe0000 1000000 20000\e; go 1000000 wd0: => setenv bootdelay 5 => saveenv .Ed
p When .Tn U-Boot/PPCBoot is lacking important commands like .Tn cp or .Tn go , or is unable to save the environment, then there is still the option to replace the .Tn Linux kernel module by
a altboot.img and save it to the same address in flash ROM. In this case you have only two options left to pass arguments:
p l -bullet -compact t Enter the interactive command line mode, after .Nm has started. This requires a serial console. t Write a fixed command line into flash, replacing the .Tn Linux initrd image. The command line is a normal .Tn ASCII file, started by the identifier .Em altboot: and terminated by any control character between 0 and 31. Example: .Dl altboot:silent ide:1111 wd0:netbsd .El .Sh SEE ALSO .Xr dhcpd 8 , .Xr diskless 8 , .Xr nfsd 8 , .Xr raidctl 8 , .Xr tftpd 8 .Sh HISTORY The .Nx Ns Tn /sandpoint .Nm first appeared in .Nx 6.0 . .Sh BUGS The Realtek Gigabit Ethernet driver does not work correctly at 1000 Mbps. Another known problem of this driver is that it runs into a timeout after a coldstart. The system has to be rebooted at least once to make it work.
Indexes created Wed Sep 24 15:09:51 GMT 2025