====== Netbooting ======

Tinycore has a native capability to be netbooted. It can also act as the host for itself.

A typical use case would be two computers, one with a cd-drive or usb-boot capability, and the other one without any easy means to boot. Another case could be the need to have TC on several computers, easily.

===== How it works =====

This section can be used as a reference to using another host, or just for curiosity.

In Tinycore the initrd is the OS. This in turn creates a lot of possibilities.
So, in netbooting, we first set up a DHCP server, authoritative, to deal out some IP addresses and to tell the clients where to get their boot fix.

Then, we set up the pxelinux bootloader, and a suitable tftpd server. Busybox is used for all the servers.

===== Doing the act =====

It is assumed you have now booted Tinycore on one machine, and that your boot media is still connected to that computer. All the clients are expected to be in the same wired LAN as the host.

==== Terminal server ====

TC terminal server is similar to the Knoppix' one, only differing in one major point. TC does not depend on the server at all after booting, so you are free to shut the host down after booting all wanted clients.

Now, fire the wizard up from the menu (TC terminal server).

The first question is about your boot device; this is to copy the kernel and initrd to RAM, in order to have as smooth operation as possible. Note the device does not have to be the actual boot device you used, if you want your clients to boot a different edition/remaster of TC.

After a short while the files are copied. Then you are asked some questions for the DHCP server:
  * the first IP address to share
  * the last IP address to share
  * the network card to use
  * DNS server(s) to share
  * subnet
  * gateway

If you have no need for an internet connection on the clients, you can accept the defaults. If you do need to connect, you'll need to give the proper details for your network.

The last question is for additional boot parameters.

Now, the server is fully operational, only waiting for your clients to connect.

==== Booting the client ====

To boot your client(s) from the network, go to their BIOS, and select "Boot order". From there, put the correct option as the first. "Boot from LAN", "PXE boot", "Network boot" or another name.
Save, and reboot. You should first see a few seconds of the BIOS preparing the PXE stack, and then sending a DHCP discovery.
In a LAN the server should respond to that instantly.

Unless you now hold alt or shift, the client will boot automatically to TC from the network. If you do hold the button, you will get a boot prompt similar to the Tinycore CD, where you can type additional boot options (if you need more, or forgot to specify them in the config phase).

====== The following sections assume that you have working servers ======
These include a PXE boot server and a working server for the network protocol you plan to use ( tftp, http, nfs, aoe, nbd, SC-101 ).\\ 
These sections are descriptions of the boot options and arguments, along with examples of their use.\\ 

This is **not** a cookie-cutter howto.\\ 
There are many ways to setup a PXE boot system.\\
We assume you know how yours works, and that you are able to pxeboot a core machine.\\ 
We also assume your other servers are configured and working, and that you know how to connect to them from a client.

====== NFS for a tce directory ======
  * As of Version 4.0, **bzImage** is replaced by **vmlinuz**.
  * As of Version 4.2, the only available initrd is **core**.
===== What this is for =====
A machine that PXE boots TCL can have its PPR on an NFS Share.  This will allow you to have a diskless workstation that can load its extensions just like a workstation with a disk or USB thumbdrive.

===== What you will need =====
If you are running TC or MC prior to Version 2.5 you will need to patch two files in tinycore.gz or microcore.gz.  The two patches can be found at 
http://forum.tinycorelinux.net/index.php?topic=2705.0

===== What is added =====
  * These patches add three new boot options.  These options add the ability to load tcz extensions via TFTP, HTTP, and NFS.
  * Core Version 2.6 and above do not need tftplist or httplist to be able to use nfsmount.
  * Core Version 2.8 adds the ability to load extensions via HTTP.
  * Core Version 2.10 adds **:no-ping** option for servers that have icmp blocked.
  * Core Version 2.11 adds **:port/** option for httplist and tftplist.

==== tftplist ( Version 2.5 ) ====
tftplist allows you to load tcz extensions via TFTP.  This can be used to load the nfs-utils.tcz from the network.

The boot options allowed are:
tftplist=server:path/list
tftplist=server/path/list ( Version 2.11 )
  * server is the tftp server name or IP address.
  * path is the tftp path to the list file.
  * list is a file that contains a list of tcz extensions to load.
If you only want to load a few extensions, and don't want the user to permanently add extensions or do backups, this may be the only option you need.

On my system:
The tftp server is openvz. My tftp server expects all file names to be relative to /tftpboot.
The extension to load is **/tftpboot/nfs/mc2/tftp/nfs-utils.tcz**.
The list is **/tftpboot/nfs/tftp/tcz**.
This file contains:
^nfs/mc2/tftp/nfs-utils.tcz^
So my boot option is **tftplist=openvz:/nfs/tftp/tcz.lst**.

If your tftpserver has icmp blocked ( can't ping ) add **:no-ping** to the end of the option.
Ex: **tftplist=openvz:/nfs/tftp/tcz.lst:no-ping**

==== httplist ( Version 2.8 ) ====
httplist allows you to load tcz extensions via HTTP.  It is similar to the tftplist option above.

The boot options allowed are:
httplist=server:path/list
httplist=server/path/list ( Version 2.11 )
httplist=server:port/path/list ( Version 2.11 )
  * server is the web server name or IP address.
  * path is the path to the list file.
  * list is a file that contains a list of tcz extensions to load.
On my system:
The http server is **openvz** on port 8000.
The extension to load is **http://openvz:8000/TCL/2.x/tcz/nfs-utils.tcz**
The list is **http://openvz/TCL/nfs.lst**.
This file contains:
^TCL/2.x/tcz/nfs-utils.tcz^
So my boot option is **httplist=openvz:8000/TCL/nfs.lst**.

If your tftpserver has icmp blocked ( can't ping ) add **:no-ping** to the end of the option.
Ex: **httplist=openvz:8000/TCL/nfs.lst:no-ping**

==== nfsmount ( Version 2.5 ) ====
nfsmount defines the nfs share that will be mounted to /mnt/nfs on the workstation.
This is probably the only bootoption you will need.
The boot option is:

nfsmount=server:share
  * server is the nfs server name or IP address
  * share is the exported share.
**Notice:** Prior to version 3.3, the second directory in the share path needed to be nfs.

On my system:
The NFS server is **openvz**.
The exported share is **/tftpboot/nfs/tc2-music**.
The boot option is **nfsmount=openvz:/tftpboot/nfs/tc2-music**.

If your tftpserver has icmp blocked ( can't ping ) add **:no-ping** to the end of the option.
Ex: **nfsmount=openvz:/tftpboot/nfs/tc2-music:no-ping**
===== Putting it all together =====
**Note:** If you are running Core 5.2 or newer, nfs-utils depends on rpcbind,tcz and libtirpc.tcz.  These will need to be added to the nfs.list.

The tftp server is sourced at /tftpboot. 
We are going to setup workstation1.  It is going to have a /mnt/nfs that corresponds to /tftpboot/nfs/ws1.
On the server **myserver**:
  - mkdir -p /tftpboot/nfs/ws1/tce
  - copy nfs-utils.tcz to /tftpboot/nfs/ws1/tce
  - create the file /tftpboot/nfs/ws1/nfs.list that contains: <code>/nfs/ws1/nfs-utils.tcz</code>
  - Copy tinycore.gz and bzImage to /tftpboot/nfs/ws1
  - add "/tftpboot/nfs/ws1 *(rw,no_root_squash)" to /etc/exports, and "exportfs -a".
  - Create a PXE config file that contains the following:
<code>
label ws1
  MENU LABEL WS1
  kernel /nfs/ws1/bzImage
  append initrd=/nfs/ws1/tinycore.gz nfsmount=myserver:/tftpboot/nfs/ws1 tftplist=myserver:/nfs/ws1/nfs.list tce=nfs/tce
</code>
When you select **ws1** from the PXE boot menu, the workstation does the following:
  - Loads TCL.
  - TFTP gets **/nfs/ws1/nfs.list** from **myserver**.
  - TFTP gets each file listed in **nfs.list** and places it in /tmp/tce, a temporary directory in RAM.
  - Mounts all applications in /tmp/tce.
  - Mounts myserver:/tftpboot/nfs/ws1 onto /mnt/nfs.
Any additional extensions installed by Appbrowser will be saved on the nfs share, and will be loaded during boot, just as you would expect with a local drive.

When you run the Backup-Restore utility, set the Device to **nfs** or **nfs/tce**.

===== Putting it all together another way. =====
If you are using pxelinux version 3.71 or greater, you can load the nfs-utils with initrd instead of using tftplist. To do this you need to create another cpio archive that contains /tmp/builtin/nfs-utils.tcz.
  - mkdir -p /tmp/tmp/builtin/optional
  - cp nfs-utils.tcz /tmp/tmp/builtin/optional
  - echo "nfs-utils.tcz" >> /tmp/tmp/builtin/onboot.lst
  - cd /tmp
  - find tmp | cpio -o -H newc | gzip -9 > /tmp/nfs-utils.cpio.gz
  - copy nfs-utils.cpio.gz to the directory containing tinycore.gz.
The PXE boot entry now is:
<code>
  MENU LABEL ws1
  kernel /nfs/ws1/bzImage
  append initrd=/nfs/ws1/tinycore.gz,/nfs/ws1/nfs-utils.cpio.gz nfsmount=myserver:/tftpboot/nfs/ws1
</code>
===== Absolute minimum method. =====
As mentioned priviously, busybox can mount /mnt/nfs without nfs-utils.
This means you can have your tce directory on an NFS share using only nfsmount. EX:
On the server **myserver**:
  - mkdir -p /tftpboot/nfs/ws1/tce
  - Copy tinycore.gz and bzImage to /tftpboot/nfs/ws1
  - add "/tftpboot/nfs/ws1 *(rw,no_root_squash)" to /etc/exports, and "exportfs -a".
  - Create a PXE config file that contains the following:
<code>
  MENU LABEL ws1
  kernel /nfs/ws1/bzImage
  append initrd=/nfs/ws1/tinycore.gz nfsmount=myserver:/tftpboot/nfs/ws1
</code>

If you intend to use NFS for anything else, PXE boot your workstation, use AppBrowser to install nfs-utils.tcz, and modify bootlocal.sh to start the NFS server or client as desired.

======AOE for a tce directory======

Starting with Version 3.8, you can use AOE ( ATA Over Ethernet ) to store your extensions and backup.
You must have a dedicated blade device formatted with a TC compatible file system.

===== Boot Codes =====
====New Boot Code====
This is accomplished with a new boot code **aoe=interface:aoedevice** that assigns and mounts an AOE device to **/mnt/aoedevice**.

Interface is the ethernet interface you will be connecting from.
If your TC is connecting over eth0, the interface is **eth0**.

Aoedevice is the blade you will be connecting to.
If your wish to use the blade in shelf 2 slot 3, the aoe device is **e2.3**,
and the boot code you use is **aoe=eth0:e2.3**.

====Existing Boot Code====
You will use the existing tce=dev boot code to assign the tce device.
Ex: **tce=e2.3**. 

=====Summary=====
Given the above example, you will need to insert the following string in the proper place in your boot loader:
^aoe=eth0:e2.3 tce=e2.3^
You can also assign home and opt.
^opt=e2.3 home=e2.3^

You can now use AppBrowser to install packages, and they will be stored on your blade along with your backup.

======NBD for a tce directory======

Starting with Version 4.0, you can use NBD ( Network Block Device ) to store your extensions and backup.
You must have a dedicated Network Block Device formatted with a TC compatible file system.

===== Boot Codes =====
====New Boot Code====
This is accomplished with a new boot code **nbd=server:port[:no-ping]** that assigns and mounts an NBD device to **/mnt/nbd0**.

Server is the server hosting the device.

Port is the port on which the server is listening.

No-ping may be needed if the server does not answer pings.

====Existing Boot Codes====
You will use the existing tce=dev boot code to assign the tce device.
^tce=nbd0^
You can also assign opt and home.
^opt=nbd0 home=nbd0^

=====Summary=====
Given a server named **myserver** listening on port **2000**, you will need to insert the following string in the proper place in your boot loader:
^nbd=myserver:2000 tce=nbd0^

You can now use AppBrowser to install packages, and they will be stored on your NBD along with your backup.

======Netgear SC101 "Toaster" for a tce directory======

With the sc101-nbd extension, you can use a Netgear SC101 "Toaster" as a Network Block Device.
You will need to use the **tftplist** or **httplist** method above to load the sc101-nbd.tcz extension.

You must preconfigure the SC101 using the Netgear supplied Windows utility, and the drive must not be password protected.

Instructions can be found at https://code.google.com/p/sc101-nbd/ .

See the info file in the apps browser for instructions on using a config file for post boot usage.
===== Boot Codes =====
====New Boot Code====
This is accomplished with a new boot code **sc101=LABEL:mountpoint** that assigns and mounts an SC101 device to **/mnt/mountpoint**.

Multiple LABEL:mountpoints can be specified, separated by ",".

If the **:mountpoint** portions are omitted, they will be sequentially assigned as **nbd0,nbd1 . . .**

If the **:mountpoint** is specified as ** :- ** , The devices will be sequentially assigned, but not mounted.  This is useful for md RAID.
 
Mountpoints are relative to /mnt unless a leading slash is included.

**sc101=ng1:-,ng2,ng3:work1,ng4:/work2** will:
^assign ng1 to /dev/nbd0 but not create a mount point,^
^assign ng2 to /dev/mbd1 and mount it on /mnt/nbd1,^
^assign ng3 to /dev/nbd2 and mount it on /mnt/work1,^
^assign ng4 to /dev/nbd3 and mount it on /work2.^


====Existing Boot Codes====
You will use the existing tce=dev boot code to assign the tce device.
^tce=nbd0^

You can also assign home and opt.
^home=nbd1 opt=nbd2^

=====Summary=====
Given an SC101 with a drive labeled as **WD120-1** you can use the following boot code to have a persistent tce directory.
^sc101=WD120-1 tce=nbd0^

You can now use AppBrowser to install packages, and they will be stored on your SC101 along with your backup.