1 AUTHOR: Csaba Henk <ekho@math-inst.hu>
5 LICENSE: The MIT License
7 SYNOPSIS: Setting up a graphical thin client using the svga vncviewer
10 This hints shows how to equip an uClibc-based bootfloppy with the svga
11 vncviewer. With this enhanced bootfloppy you can turn even low-end
12 computers to thin clients with the functionality of an X terminal. We
13 also describe a possible minimalistic server + thin client configuration.
16 This hint should be useable on any not too aged Linux installation with
17 a non-broken toolchain. It was tested on a (by and large) LFS-4.0
21 http://www.linuxfromscratch.org/hints/downloads/attachments/svnc-thinclient/make_uclibc-libvcauth
22 http://www.linuxfromscratch.org/hints/downloads/attachments/svnc-thinclient/make_uclibc-svncviewer
23 http://www.linuxfromscratch.org/patches/downloads/svgalib/svgalib-1.9.18-demos_Makefile-1.patch
24 http://www.linuxfromscratch.org/patches/downloads/svnc/svnc-0.1-modeforce-1.patch
34 Completing the bootfloppy
35 Installing more of uClibc
39 Setting up the network environment
40 Setting up general server programs
41 Installing the vnc server
42 Connecting from client to server
51 * This hint is co-developed with the uclibc-bootfloppy hint in the
52 framework of the lowlife project,
54 http://www.math-inst.hu/~ekho/lowlife/
56 This file belongs to lowlife-0.5.1.
58 * For the most recent version check out
60 http://www.math-inst.hu/~ekho/lowlife/svnc-thinclient.txt
62 * Comments, ideas, critics, flames are welcome.
64 * (If you are an LFS user, you can skip this.) Although this document is
65 formally an LFS hint, you can see use of it without knowing what LFS is
66 (I tried to write it keeping this possibility in mind). Anyway, I
67 recommend you to check out what LFS is. If you are not familiar with
68 compiling source code in unix/linux environment, then there is no use of
69 going on without checking out what LFS is. Consult the following docs
72 http://www.linuxfromscratch.org/lfs/whatislfs.html
73 http://www.linuxfromscratch.org/faq/
74 http://www.linuxfromscratch.org/hints/downloads/files/essential_prereading.txt
75 http://www.linuxfromscratch.org/lfs/view/stable/preface/prerequisites.html
80 As the Linux Xterminal mini-HOWTO claims: "Ideally, an XT is silent,
81 swift, and deadly". A cheap and great way to achieve this ideal is to
82 use old PC's as terminals. Two issues arise here:
84 1) How to make them display X?
85 2) How to make them silent?
87 Concerning 2), the possible sources of noise are fans and HD. In case
88 of old PC's (486s and old Pentiums) the CPU needs no fan -- if there
89 is any fan, you can find it at the power supply, and it's not a big
90 risk to plug that out. This is where oldness becomes a feature.
91 Concerning the HD: to make the it quiet, you should avoid using it.
92 An alternative is using a ramdisk for carrying your root filesystem.
93 The most easy way to make the kernel mount a ramdisk as root
94 filesystem is booting from a floppy. This is why I use a bootfloppy.
96 This design implies that in case of an old PC, we will be tight on
97 memory. One kind of reaction to this circumstance is trying to trim
98 down X for the floppy. I chose an other way, namely, displaying X via
99 vnc: we put svgalib + the svga vncviewer to the floppy.
101 This hint is a continuation of the uclibc-bootfloppy hint (
103 http://www.linuxfromscratch.org/hints/downloads/files/uclibc-bootfloppy.txt
104 http://www.math-inst.hu/~ekho/lowlife/uclibc-bootfloppy.txt
106 ) which describes how to put together a bootfloppy based on recent linux
107 kernel, the uClibc C library and busybox. The steps described here
108 should be performed when you get to the "Other programs" chapter of the
109 uclibc-bootfloppy hint.
111 This way we get a "bleeding edge" bootfloppy with recent versions of
112 the used programs, and this setup needs no more than 7M RAM -- in
113 this value kernel mem usage, ramdisk size, svncviewer displaying a
114 bunch of graphic programs are all included. This value could still be
115 decreased by using older stuff; why do I insist on being at the
116 bleeding edge? See the answer in the uclibc-bootfloppy hint.
118 This hint,additional info and downloadable bootdisk image with svnc
119 can be found at my homepage (or at its mirror):
121 http://www.math-inst.hu/~ekho/lowlife/
122 http://www.personal.ceu.hu/students/01/Csaba_Henk/lowlife/
124 In this hint we the assume that you use an x86 PC (both for making and
125 booting the floppy) with gcc. You may try to port it to another
126 architecture / compiler. Doing it on another architecture should not
127 be hard. Doing it with another compiler depends on how much does
128 uClibc support that compiler.
130 If you copy command from this hint to your shell, be careful that
131 line-terminating backslashes (\) will keep their position (no whitespace
132 characters should follow them). A possible solution is open this hint in
133 the Vim GUI, and copy'n'paste from there.
138 Here I list the programs which we need for the bootfloppy and the ones
139 which are used in the particular server + client setup which will be
140 described in the sequel.
142 Generally you are encouraged to use the most update versions of the
143 programs (and your favorite distributions, if there are more of them).
144 Still there are some items where I have some additional comment on the
145 version/distribution; these are marked with (!). You can find the
146 version notes at the end of this hint.
151 http://prdownloads.sourceforge.net/vnc-tight/tightvnc-1.2.*_unixsrc.tar.bz2
153 some kind of telnet daemon
154 some kind of tftp daemon
156 * The client (bootfloppy) side
159 http://www.arava.co.il/matan/svgalib/svgalib-1.9.18.tar.gz
161 ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/svnc-0.1.tgz
162 and the mirrors listed in
163 http://www.realvnc.com/pipermail/vnc-list/2002-June/031178.html
164 tightvnc (only needed for compiling svnc)
167 Completing the bootfloppy
168 =========================
170 First you need a bootfloppy development environment. Setting up one is
171 described in the uclibc-bootfloppy hint. Do what the uclibc-bootfloppy
172 hint tells you, until you get to the "Other programs" chapter.
174 Then do the following; you are supposed to work as the bootdisk user in
175 the present chapter (ie., type
179 if you didn't do it yet).
181 Installing more of uClibc
182 -------------------------
184 For svgalib we need the math libraries of uClibc. If you installed gpm
185 to the floppy filesystem correctly, you already have them. If you don't
186 have them on the floppy filesystem, type:
188 cd /usr/i386-linux-uclibc/lib/ &&
189 cp -a libm-* libm.so.0 ~/rfloppy/lib
194 First some necessary corrections for the 1.9.18 version of svgalib;
195 hopefully these will be unnecessary for subsequent releases. You find a
198 http://www.linuxfromscratch.org/patches/downloads/svgalib/svgalib-1.9.18-Makefiles-1.patch
202 http://www.math-inst.hu/~ekho/lowlife/patches/svgalib-1.9.18-Makefiles-1.patch
204 or in the patches directory if you read this hint as a file of the
205 lowlife tarball avaliable at
207 http://www.math-inst.hu/~ekho/lowlife
209 This patch corrects some typos in the Makefiles. Put the patch to the
210 svgalib source dir as svgalib-1.9.18-Makefiles-1.patch. Then type
212 ln -s ../egadrv.c src/drivers &&
213 patch -Np1 -i svgalib-1.9.18-Makefiles-1.patch
215 (the first command is the correction of a file misplacement).
217 These were the version-specific corrections. Now let's go for the real
220 Adjust the list of supported drivers in Makefile.cfg according to
221 your needs. By carefully choosing the few drivers you need, you can
222 decrease the size of the binary with about 100 kb or maybe more! However,
223 our filesystem is big enough for the svga library with all default drivers
226 Now we compile svgalib and install it to the directory of the floppy's
227 filesystem. In this development version of svgalib the svga-aware
228 programs are needed no more to run as setuid root, but a kernel module
229 is to be loaded for using svgalib. The commands below also compile and
230 install the kernel module. Store the location of your kernel for the
231 floppy in the variable KERNEL (eg., KERNEL=$HOME/linux-2.4.22), and then
237 strip libvga$q.so.1.9.*
238 ln -s libvga$q.so.1.9.* libvga$q.so.1
239 ln -s libvga$q.so.1 libvga$q.so
241 mkdir -p $HOME/rfloppy/usr/lib &&
242 cp -a libvga* $HOME/rfloppy/usr/lib &&
243 # Now comes the compilation of the module
244 cd ../kernel/svgalib_helper &&
245 make KDIR="$KERNEL" &&
246 mkdir -p $HOME/rfloppy/lib/modules &&
247 cp svgalib_helper.o $HOME/rfloppy/lib/modules &&
250 Also create the file $HOME/rfloppy/etc/vga/libvga.config, and put into it
251 your mouse type at least. Eg., my libvga.config looks like:
256 If you feel like, you can also compile the svga test suite. It is useful
257 if you want to custom-tailor your svga configuration (which means
258 adjusting the libvga.config file). To do so, type
261 make "LIBS=../sharedlib/libvga.so ../sharedlib/libvgagl.so" &&
263 make "LIBS=../sharedlib/libvga.so ../sharedlib/libvgagl.so" \
264 "INCLUDES = -I../include -I. -I../src -I../gl" &&
267 in the svgalib source directory. You will find the executables in the
268 demos and threeDKit directories.
270 Do not delete the svgalib source dir -- we will need it in the following
273 Installing svncviewer
274 ---------------------
276 Do not yet extract the svncviewer tarball! The following commands will
277 assume that the svgalib source dir, the tightvnc and svncviewer tarballs
278 and you (ie., the bootdisk user) are at $HOME.
280 To get svncviewer compiled, we need the libvncauth.a library form the
281 tightvnc distribution. (Thus svncviewer is compiled inside the vnc
282 source tree.) The usual way to compile both of libvncauth.a and
283 svncviewer is to create makefiles with the xmkmf utility, and then
286 However, xmkmf will not work with uClibc (unless we build X against
287 uClibc, and we don't want to do that). Therefore we compile both of
288 libvncauth.a and svncviewer in the following manner:
290 * run xmkmf (imake) using glibc;
292 * run make with options for using uClibc and local svgalib, and for size
295 In practice this means the following: first we define a variable which
296 stores the relative path from the svncviewer source dir to svgalib
297 source dir (we need this path as we don't install the uClibc-linked
298 svgalib on the development platform). If you follow my setup faithfully,
301 SVGADIR=../../svgalib-1.9.18
303 (otherwise find it out by yourself :).
305 Here I tell you about a patch I made for svncviewer:
307 http://www.linuxfromscratch.org/patches/downloads/svnc/svnc-0.1-modeforce-1.patch
308 http://www.math-inst.hu/~ekho/lowlife/patches/svnc-0.1-modeforce-1.patch
310 This introduces a -mode option for svncviewer with which you can force
311 svncviewer to use a given svga mode (these modes are described in the
312 svgalib docs or check out the vgatest executable of the svgalib test
313 kit). If you don't apply the patch just execute the following sequence
314 of commands, otherwise take a break for patching when its time comes.
316 bzcat tightvnc-1.2.*_unixsrc.tar.bz2 | tar xv &&
318 tar xvzf ../svnc-0.1.tgz &&
321 make "CC=i386-uclibc-gcc" "CDEBUGFLAGS = $CFLAGS -fno-strength-reduce" \
322 "AR = i386-uclibc-ar clq" &&
324 # Now apply patch if you want to
326 make "CC=i386-uclibc-gcc" "CDEBUGFLAGS = $CFLAGS -fno-strength-reduce" \
327 "INCLUDES = -I../include -I. -I$SVGADIR/include -I$SVGADIR/gl" \
328 "SVGALIB = $SVGADIR/sharedlib/libvga.so $SVGADIR/sharedlib/libvgagl.so" &&
330 mkdir -p $HOME/rfloppy/usr/bin &&
331 cp svncviewer $HOME/rfloppy/usr/bin
333 If you intend to compile svncviewer in an environment without X (ie.,
334 you don't have xmkmf), then try to compile libvncauth.a and
335 svncviewer with the help of the following scripts (they are simply
336 the output of the respective make commands; I give away these and not
337 the Makefiles because xmkmf-made Makefiles are huge and illegible):
338 find them together among attachments,
340 http://www.linuxfromscratch.org/hints/downloads/attachments/svnc-thinclient/
344 http://www.math-inst.hu/~ekho/lowlife/non-X/make_uclibc-libvncauth
345 http://www.math-inst.hu/~ekho/lowlife/non-X/make_uclibc-svncviewer
347 Creating the bootdisk
348 ---------------------
350 Proceed on as it is described in the similarly named chapter of the
351 uclibc-bootdisk hint.
354 Setting up the network environment
355 ==================================
357 You have the bootdisk with the svga vncviewer. If you know what you want
358 to do with it, you have clear ideas that in what network environment you
359 will use it, then the rest of the hint is not too interesting for you.
361 In the sequel we describe a minimalist local network setup: a server
362 machine running a vnc server, and a client machine booted with our
363 bootfloppy, which can connect to the server in three basic ways: it
364 can transfer files via tftp, it can get a character terminal on the
365 server via telnet, and it can display X desktops via vnc. Using the
366 tftp and telnet services requires that you enabled the respective
367 clients when you compiled busybox. (And you will also need ifconfig
368 being enabled in busybox.)
370 We will assume that you connect the two machines directly (without a
371 switch or things like that) and that you have a free network interface
372 (network card, serial/parallel port) on both machines.
374 Setting up general server programs
375 ----------------------------------
377 Fix an unused IP address for the server and the client side, from
378 the private network IP-address range, from the same network class, and
379 store it in the $SERVER and $CLIENT variables, respectively. Eg., I
385 Then you should install xinetd (or alternatively, inetd), some telnet
386 daemon, and some tftp daemon. These are covered by the BLFS book
389 http://beyond.linuxfromscratch.org
391 ). Choose a directory for tftp transfers, store its value in the
392 variable $TRANSFER. (That is, tftp clients can download files located in
393 $TRANSFER, and can upload files to $TRANSFER.) Choose carefully the
394 list of those users/groups which can write to $TRANSFER.
396 Configure xinetd to run telnetd and tftpd bound to $SERVER like this
397 (the names of the executables may be different on your system; and
398 consider that by the settings below tftp is ran by a specific user):
406 server = /usr/sbin/in.telnetd
409 log_on_failure += USERID
418 server = /usr/sbin/tftpd
419 server_args = $TRANSFER
422 }" >> /etc/xinetd.conf
424 Note that binding these services to $SERVER is essential for security --
425 telnet transfers data unencrypted and tftp transfers data without asking
428 Now you can configure the network interface on the server -- in the
429 following example we use plip:
431 ifconfig plip0 $SERVER pointopoint $CLIENT
433 (It's your homework to find out how to get it executed at startup.)
435 Restart xinetd; in an "official" LFS/BLFS system it is done with
437 /etc/rc.d/init.d/xinetd restart
439 Installing the vnc server
440 -------------------------
442 In this setup we will install the vnc server in a standalone way, that
443 is, it won't be handled by xinetd so you will have to start it manually.
444 (One benefit of this approach that in this case the vnc session remains
445 alive after a viewer disconnects, so you can use it as a portable X
446 desktop, "the screen of X".) If you would like a "vnc + xinetd"-ish vnc
447 setup, check out the tightvnc hint (
449 http://www.linuxfromscratch.org/hints/downloads/files/tightvnc.txt
453 Install tightvnc with the following commands:
461 sed '/^ *\$fontPath/s%^%#%' vncserver > vncserver.tmp &&
462 mv vncserver.tmp vncserver &&
463 ./vncinstall /usr/bin /usr/share/man
467 "sed '/^ *\$fontPath/s%^%#%' vncserver [...]" :
469 this command comments the $fontPath variable out, as I see no effect of
470 setting it other than getting error messages (it may be different on
473 Note: the above commands do not cover the installation of the java
474 viewer, which enables java-supporting browsers to display vnc desktops.
475 The java viewer is shipped with the tightvnc source code in a
476 precompiled form; however, if you want to act according to LFS spirit,
477 *do not* install it, rather download the tightvnc-1.2.*_javasrc package
478 from the tightvnc site, and compile it yourself. That's pretty
481 Connecting from client to server
482 --------------------------------
484 Now its time to boot the floppy on the client machine. We will use the
485 $SERVER, $CLIENT variables with the same values on the client machine as
488 When you get the prompt on the client, set up the network -- eg.,
489 continuing the above example with plip:
491 ifconfig plip0 $CLIENT pointopoint $SERVER
493 * If all is nice, you can get a prompt of the server on the client simply by
498 * Transferring files between the server and client is as follows:
500 - downloading the file foo from server to client: on the server, put foo
501 into $TRANSFER, make it world-readable, then on the client: get sure that
502 foo does not exist in the current directory, then type:
504 tftp -g -r foo $SERVER
506 - uploading the file foo from client to server: on the server type
509 chmod a+w $TRANSFER/foo
511 then on the client type
513 tftp -p -l foo $SERVER
515 -- its primitive, but saves your floppy from the bloat.
517 * And getting an X desktop via vnc: at the server, login as the user
518 whose desktop is to be reached from the client (you can use the telnet
519 of the client). Then type:
523 (you may need to pass -geometry and -depth options to be compatible with
524 the video capabilities of the client).
528 insmod /lib/modules/svgalib_helper.o &&
531 and see the desktop of the server.
535 * pass the "-interface $SERVER" option to the vnc server if you worry
536 for security and you want to make sure that only the client has access to
539 * pass the "-compatiblekbd" option to the vnc server if you want to use
540 non-standard characters; eg., this way typing Alt+i in an xterm gives
541 you an acuted e. This is the way to go for people whose language uses
542 nonstandard characters, as vnc does not support xmodmap well.
544 There is a more tricky way of using vnc: with the help of ssh tunneling
545 you can reach any vnc server from the client which is reachable from the
546 server. Say you run a vnc server at pistike.org, on display 1 (port
547 5901), as user steve. On the server type
549 ssh -g -L 5902:localhost:5901 steve@pistike.org
551 This forwards port 5902 of the server to port 5901 of pistike.org. Thus
556 on the client, you will be connected to the vnc server of pistike.org.
557 Moreover, the connection between the server and pistike.org will be
570 As it can be read in the svgalib.org site, "Pre releases of svgalib-2
571 will be called 1.9.x, with no pre, but they are still very
572 experimental." Why do we use experimental version? Simply because it
573 works much more flawlessly: the stable release (svgalib-1.4.3) was also
574 willing to compile, but it gave me segmentation faults. Note that the
575 1.9.18 version has some lesser bugs which are corrected in this hint;
576 these corrections are likely to become unnecessary with a new release of
577 svgalib. Compilation of the svgalib_helper has changed in 1.9.18.
581 You can find two different kind of releases of the svga vncviewer: there
582 is the original one, that's used in this hint, and there are the Debian
585 http://packages.qa.debian.org/s/svncviewer.html
587 ). For me the deb version seems to be an unclever dirty hack: its
588 maintainer changed keyboard handling in way such that you can compile
589 the program with an arbitrary keyboard layout (it's shipped with US and
590 German layouts), but this way several keyboard combination got disabled:
591 eg., killing the viewer with Ctrl+Alt+Backspace does not work; the
592 Ctrl+Alt+Left/Right combinations of icewm for changing desktops neither
593 work. And the source ships with precompiled libvncauth.a and svncviewer
594 and bunch of other unnecessary things; it's quite annoying (the manpage
595 is fine, tho). So I sticked with the oldie-but-goldie original version
598 This hint is co-developed with the uclibc-bootfloppy hint in the
599 framework of the lowlife project, thus the following subsections regard
600 to the whole lowlife project.
605 The list below is about both of the uclibc-bootfloppy and the
606 svnc-thinclient hints.
608 The following weirdnesses are probably due to the respective programs
609 and not to doing something wrong in these hints.
611 * Sometimes when switching to another terminal and then back to the
612 svga vncviewer the keyboard gets screwed up. Using serial mouse,
613 sometimes the keyboard gets screwed up without any obvious reason.
614 However, after restarting the viewer, things behave normally again.
616 * Using libvgagl-dependent programs (like svncviewer) on my 486
617 laptop, I see a horizontal white line at half height of the screen.
618 I wonder whether this occurs with other LCD monitors.
623 Now it seems that the uclibc-bootfloppy and svnc-thinclient hints got
624 quite close to their idea: you set up the development environment, su to
625 bootdisk user, type in some commands, finally put a floppy to the drive
626 and run the mkbootdisk script, and you have the bootfloppy.
628 However, I can say only "Now it seems..." but I can't say "Now it is..."
629 -- without testing the stuff by many people and getting feedback I
632 So the main TODO is to be done by you, kind reader: test and report!!
634 After it happens, these hints can be claimed to be mature.
636 Another TODO will be in the future to upgrade to newer versions of the
637 installed programs, if new versions come out.
641 (This hint is co-developed with the uclibc-bootfloppy hint in the
642 framework of the lowlife project, thus this section regards to the whole
645 * Useful information resources:
647 - busybox mailing list
648 - uClibc mailing list archives
649 - vnc mailing list archives
650 - "Creating a Custom Bootdisk" chapter of the BLFS book
653 - http://ebusiness.gbdirect.co.uk/case_studies/xterminal.html
654 - the LODS project (http://www.khk.net/lods/index.html)
655 - the tomsrtbt project (http://www.toms.net/rb/)
656 * Archaic had some useful advice about trimming the root filesys (/etc).
657 * Following the advice of Bill Maltby, "rdev $DISK 0,0" is used rather
658 than "rdev $DISK $DISK" or "rdev $DISK 2,0".
662 (This hint is co-developed with the uclibc-bootfloppy hint in the
663 framework of the lowlife project, thus this section regards to the whole
666 Important changes are tagged with (!)
667 Very important changes are tagged with (!!)
674 * Removed the loopmnt script. Now the files are just
675 simply to put into a directory and not to an ext2 filesystem (!!)
676 * Moved gpm from svnc-x_terminal.txt to uclibc-bootfloppy.txt
677 (as I realized that svgalib does not use gpm)
678 * Got rid of the ugly /usr/i386-linux-uclibc/lib/ ->
679 ../../lib symlink (!!)
680 * Many changes in the mkbootdisk script:
681 - encorporates functionality of ceased loopmnt script
682 - it does no more belong to a specific bootdisk user
683 - the floppy image can be dumped to stdout
685 * Now devfs is *the* way to go (!)
686 * Removed /etc/{group,passwd,fstab}
687 * Fixes, prettifying:
688 - Added Changelog, links to it, VERSION, trivial BUGS file
689 - Reduced egotripping in the 1st paragraph of index.html
690 - Added some explanation about the devfsd patch in index.html
691 - Removed the only reference to Micro$oft from the hints ;) (ie.
692 now there is shown a more common example of mouse settings in
693 libvga.config, in svnc-x_terminal.txt)
694 - "Closing remarks" in svnc-x_terminal.txt rethought
695 - Typo fixes; wording developed
696 - Applied the changes in the hints to the distributed floppy
698 - Minor changes in index.html
701 * Got rid of hacking system files -- now after putting together
702 the development environment all stuff is done non-privileged (!!)
703 * Added modeforce patch of svncviewer
704 * Eliminating sed hacks -- rather using make with options (!)
705 * Fixes of typos in svgalib-1.9.17 Makefiles are collected in a
707 * svgalib compilation streamlined
708 * Using rdev as "rdev $DISK 0,0" (!)
709 * The mkbootdisk script now:
710 - supports safe tempfile creation
711 - hopefully work with all possible filenames
713 * Fixes, prettifying:
714 - Fixed some quite confusing typos
715 - Changelog reorganized
716 - mkbootdisk now has more transparent indentation
717 - Homepage domainname changed to www.math-inst.hu from
718 www.renyi.hu (same domain, another alias)
721 * Reorganized according to new LFS hint format (see
722 http://www.linuxfromscratch.org/hints/submit.html) (!)
723 * Changed license to MIT (!)
724 * First compiled piece is kernel, thus uClibc can use correct headers
726 * Upgraded to uClibc-0.9.21, svgalib-1.9.18
727 * Demofloppy got updated as well and put to a disctinct package
728 * Fixes, prettifying:
729 - Some instructions got more streamlined
730 - Added chroot test of the filesystem
731 - The filename svnc-x_terminal.txt changed to svnc-thinclient.txt
732 - index.html updated and made more readable
734 - Added list of all attachments to both of uclibc-bootfloppy
735 and svnc-thinclient hints
736 - More BLFS-friendly intro text in uclibc-bootfloppy hint
737 - Added fdformat advice