Sorry for the inconvenience.  Known Navigation header breakage, its being "rebuilt" but forward nav should be ok now.
There may be other unforeseen breakage primarily in the handbook portion of the wiki.
The Table Of Contents section of each "PC-BSD® Users Handbook" page may be the best workaround.

Thin Client/9.2

From PC-BSD Wiki
Revision as of 09:38, 22 August 2013 by Drulavigne (Talk | contribs)

Jump to: navigation, search

(Sorry for the inconvenience)


The pc-thinclient script has been improved for PC-BSD® 9.1 by adding the following features:

  • the ability to create an installation server. Now when you first initialize the pc-thinclient script, you will be asked if you want to setup a PXE Boot Desktop Server or a PXE Boot Install Server.
  • when configuring a PXE Boot Install Server, all the necessary bits for PXE booting are taken care of, allowing you to prepare for PXE installs within minutes.
  • the ability to create unattended installation scripts for the PXE Boot Install Server.

This section demonstrates how to configure and use both the PXE Boot Desktop Server and the PXE Boot Install Server.

Creating a PXE Boot Desktop Server

A PC-BSD® PXE Boot Desktop Server allows you to automatically configure a network of diskless computers[1] where each computer has a network interface card capable of PXE[2] booting. When a client boots from their network interface instead of their hard disk, they automatically connect to the PXE Boot Desktop Server and receive a login window. Once authenticated, they can use PC-BSD®, even if PC-BSD® is not installed on their own computer and even if their computer does not have a hard drive.

To prepare your PC-BSD® system for a PXE Boot Desktop Server configuration, perform these tasks first:

  1. If the diskless clients will require Internet access, install two network cards where one NIC is connected to the Internet and the other is connected to a private LAN from which the thin clients can PXE boot from.
  2. The PC-BSD® system should have lots of RAM installed, especially if multiple clients will be connecting. It is recommended that you use a 64-bit system with as much RAM installed as possible.
  3. Set aside an hour or so as the system will need to download and install the kernel and applications it needs in order to support the PXE environment. The script will automatically build a 32-bit environment (even on a 64-bit system) as most PXE boot clients are 32-bit.

To configure the PC-BSD® system as a PXE Boot Desktop Server, run the following script as the superuser:

/usr/local/bin/pc-thinclient will install the components to convert this system into a thin-client server. 
Continue? (Y/N) y
Do you wish to install the dhcpd server port or use an external server?
If you wish to use an external server please make sure it supports adding next server and bootfile name options.

If you wish to have the PC-BSD® system act as the DHCP server, type d. If the network already has a configured DHCP server, type e. After making your selection, press enter to continue:

Do you wish to make this a remote X desktop server or install server? (r/i) r}}

If your intent is to install a PXE Boot Desktop Server, input r and press enter. If you previously typed d and a DHCP server is not already installed, it will be installed for you. Once the DHCP server is installed, the tools needed in the PXE environment will be installed and messages will indicate the progress. Once everything is installed, you will see this message:

Setting up system for PXE booting...

What NIC do you wish DHCPD to listen on? (I.E. re0)

nic) em0

Input the FreeBSD device name of the interface that is attached to the local network containing the diskless workstations. This interface will run the DHCP server and should not be connected to a network with another DHCP server running. In the example shown here, the user has input the em0 interface. If you are unsure of the device name, type ifconfig from another terminal.

The script will now configure the specified interface and start the required services:

Starting /etc/rc.d/nfsd...OK

Starting /etc/rc.d/inetd...OK Starting /usr/local/etc/rc.d/isc-dhcpd...OK

You will need to reboot the system for the login manager changes to take effect.

Your system is now setup to do PXE booting!

Go to Control PanelGDM Configuration and check the box Enable XDMCP. If you forget this step, clients will not be able to receive an X session when they connect.

The installation creates a chroot directory that contains a small PXE image that is used by clients to launch Xorg and connect to the PXE Boot Desktop Server. You can access this chroot by typing this command as the superuser:

chroot /usr/home/thinclient

Running pkg_info within the chroot will show which X components and drivers are available. Should you need to install additional video drivers, use pkg_add within the chroot. When you are finished using the chroot, type exit to leave it.

The thin client script installs and configures the following services:

NFS: the Network File System is a protocol for sharing files on a network. It has been configured to allow clients on the network attached to the interface that you specified to connect to the thin client server. Its configuration file is located in /etc/exports.

TFTP: the Trivial File Transfer Protocol is a light-weight version of FTP used to transfer configuration or boot files between machines. The PXE network cards on the diskless computers will use TFTP to receive their configuration information. This service was enabled in /etc/inetd.conf with a home directory of /home/thinclient.

DHCP: the Dynamic Host Configuration Protocol is used to configure IP addressing info on the diskless workstations. It has been configured to assign addresses for the network attached to the interface that you specified. Its configuration file is located in /usr/local/etc/dhcpd.conf.

The thin client script also creates the pxeboot user with the default password thinclient. This username and password is used to save the working Xorg configuration files for each of the diskless computers. It is highly recommended that you change this password right away by running this command as the superuser:

passwd pxeboot

You will also need to create the users that will connect to the system. You can do so using User Manager or by typing adduser at the command line and following the prompts.

Connecting to the PXE Boot Desktop Server

After a successful installation and reboot of the PXE Boot Desktop Server, the DHCP service will be running on the NIC you specified. Make sure that this NIC and a PXE capable client are connected to the same hub or switch. When you boot up the client, PXE should automatically obtain an IP address and begin to load PC-BSD®. If it does not, review the boot order settings in the BIOS on the client to make sure that PXE is listed first.

After the boot process has finished, the client will be brought to this prompt:

No saved xorg-config for this MAC: <MAC_Address> Do you wish to setup a custom xorg.conf for this system? (Y/N)

If you wait 10 seconds, this message will timeout, and the client will bring up X in 1024x768 mode. If this is not the resolution that you wish to use, type "Y" at the prompt and hit enter to bring up the Xorg Configuration screen. In this menu, you will be able to setup your own custom xorg.conf file, auto-detect settings, and test the new configuration. When finished, choose "Save working config" to send this configuration to the PXE Boot Desktop Server. This will prompt for the password of the pxeboot user. Once authenticated, the file will be saved by the client's MAC address in /home/pxeboot/mnt/xorg-config/<mac>.conf. The next time you boot the client, it will automatically use the saved xorg.conf file and bring the system to the PC-BSD® login screen.

Translations:Handbook translating/common/11 In order for the login to succeed, the user account must already exist on the PXE Boot Desktop Server.

The client's boot environment is located in /home/pxeboot. This is mounted read-only during the PXE boot process to allow the client to bootup and create an XDCMP connection to the server.

Once logged in to the PXE Boot Desktop Server, using PC-BSD® will be the same as if you had installed PC-BSD® on the client system. You will be able to use AppCafe® to install software and to save and use the files in your home directory.

Uninstalling the PXE Boot Desktop Server

Use the -remove option if you wish to uninstall the PXE Boot Desktop Server:

pc-thinclient -remove Removing /usr/home/thinclient

This will remove the PXE environment from the system. If you are finished using the PXE boot services, you can stop them using these commands:

service nfsd stop

service inetd stop

service isc-dhcpd stop

and prevent them from restarting by removing these lines from /etc/rc.conf:

# pc-thinclient configuration

dhcpd_enable="YES" dhcpd_ifaces="em0" portmap_enable="YES" nfs_server_enable="YES" inetd_enable="YES"


Your interface name and IP address may differ from those in the example.

Creating a PXE Boot Install Server

A PC-BSD® PXE Boot Desktop Server can be used to install PC-BSD®, FreeBSD, or TrueOS® onto computers who connect to the server using PXE. The installations can be interactive or fully automated. The PXE Boot Desktop Server supports multiple, concurrent installations with the only limiting factor being the server's disk I/O and the network's bandwidth.

The installation of the PXE Boot Install Server starts the same way, except this time you select i when prompted:


/usr/local/bin/pc-thinclient will install the components to convert this system into a thin-client server. Continue? (Y/N) y Do you wish to make this a remote X desktop server or install server? (r/i) i

Fetching FreeBSD environment... This may take a while... Extracting PC-BSD environment... This may take a while... Setting up system for PXE booting... What NIC do you wish DHCPD to listen on? (I.E. re0) nic) em0 Starting /etc/rc.d/nfsd...OK Starting /etc/rc.d/inetd...OK Starting /usr/local/etc/rc.d/isc-dhcpd...OK

To perform system installations, place your custom pc-sysinstall scripts in: /usr/home/thinclient/installscripts An example script is provided in the above directory For unattended installations, save your pc-sysinstall script as: /usr/home/thinclient/installscripts/unattended.cfg

Your system is now setup to do PXE booting!

Connecting to and Customizing the PXE Boot Install Server

Once the PXE Boot Install Server is installed, try to PXE boot a client which is connected to the same network. If the client boots successfully, you will see the installation screen shown in Figure 9.8a.

Figure 9.8a: PXE Boot Installation Menu

By default, selecting “install” from the boot menu will use the /usr/home/thinclient/installscripts/pc-sysinstall.example script which installs a basic FreeBSD system. In addition to starting an installation, this menu provides an emergency shell prompt. This can be useful if you have a system which can no longer boot and you wish to either access the disk's contents or attempt to repair the installation.

Any scripts that you create and place in the /usr/home/thinclient/installscripts/ directory will be selectable as an installation option within the PXE client boot menu. Tables 5.4a and 5.4b in Creating an Automated Installation with pc-sysinstall summarize the available configuration options when creating an installation script. Alternately, every time you install PC-BSD, the installation script is automatically saved to /root/pc-sysinstall.cfg. This means that if you wish to repeat an installation, you simply need to copy that file to the /usr/home/thinclient/installscripts/ directory on the PXE Boot Install Server.

The PXE Boot Install Server also supports completely unattended installations. To perform fully-automated installations over the PXE interface, create a configuration script named /usr/home/thinclient/installscripts/unattended.cfg. When a PXE client first boots, it checks for the existence of the unattended.cfg file, and if found, it will automatically use it for installation. Some caution should be taken when using this method since simply plugging a PXE boot client into the wrong LAN cable could cause it to be re-installed.

Translations:Handbook translating/common/14

Other languages:German 5% • ‎English 100% • ‎French 4%
Personal tools