<?xml version="1.0" encoding="UTF-8"?>
<!-- $Header: /var/www/viewcvs.gentoo.org/raw_cvs/gentoo/xml/htdocs/doc/en/Attic/nx-guide.xml,v 1.4 2006/05/15 12:34:33 nightmorph Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide link="/doc/en/nx-guide.xml">
<title>Running NX On Gentoo Linux</title>
<author title="Author">
  <mail link="stuart@gentoo.org">Stuart Herbert</mail>
</author>

<abstract>
This guide shows you how to install and upgrade NoMachine's NX server and
client products.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1.1</version>
<date>2006-05-15</date>

<chapter>
<title>Introduction</title>
<section>
<title>What is NX?</title>
<body>

<p>
NX is a server/client solution for connecting to your X11 desktop from another
machine.  It's the UNIX equivalent of Microsoft's Terminal Services and Remote
Desktop Connection.  The server component is available for a number of Linux
distributions, and for other UNIX platforms too.  The client is available for
all the server platforms, and for Microsoft Windows.
</p>

<p>
One of NX's great strengths is its built-in compression support.  This makes it
possible to remotely use your X11 desktop over low-bandwidth links (802.11
WiFi, cable, broadband and satellite links) with little or no loss in
performance.  To see for yourself, NoMachine offer remote access to their <uri link="http://www.nomachine.com/testdrive/">Test Drive</uri> server, so that you
can try before you buy.
</p>

<p>
The latest version of NX - currently in beta testing - will allow you to
reconnect to an NX session you previously used.  Think <c>screen -rd</c> for
X11, and you'll be on the right track. (And shame on you if you don't know
<c>screen</c> ;-)
</p>

</body>
</section>
<section>
<title>Obtaining An NX License</title>
<body>

<p>
NX is a commercial product.  To use the NX Server on Gentoo Linux, you must
first purchase an NX Server license from <uri>http://www.nomachine.com</uri>.
The NX Client can be installed and used <e>without</e> a license.
</p>

<p>
There are three different editions of NX Server available: personal, small
business edition, and enterprise.  The only difference that I know of between
the different editions is the number of users that each edition supports.
Please make sure that you buy a license for the right edition!
</p>

<p>
When you purchase your license, you will be asked which operating system you
are buying for.  Unfortunately, the NoMachine website doesn't list Gentoo Linux
as one of the choices.  Please buy a license for 'RedHat 9.0'.  We use the
'RedHat 9.0' binaries for NX on Gentoo Linux.
</p>

<impo>
There is no need for you to download any software from NoMachine's website.
Portage will do this for you when you use <c>emerge</c>.
</impo>

</body>
</section>
<section>
<title>Supported Platforms</title>
<body>

<p>
At the moment, NX is only availble on the <e>x86</e> platform.  <e>amd64</e>
and <e>ia32</e> users may have success too, but as I don't have either of these
hardware platforms, I can't test or support NX on them for now.  If anyone
would like to donate ia32 or amd64 hardware to help me support NX on these
platforms, please contact me via <uri link="mailto:stuart@gentoo.org">email</uri>.
</p>

</body>
</section>
<section>
<title>Acknowledgements</title>
<body>

<p>
I'd like to thank Gian Filippo Pinzari and all the staff at NoMachine for their
help and support in bringing NX to Gentoo Linux.
</p>

<p>
Just to be clear: I am not an employee of NoMachine, and I'm not connected with
the company in any way.  I'm just a <e>very</e> satisfied customer.  Most of my
Gentoo work is done via NX, so for me it's one of the most important packages
that I look after in Gentoo Linux.
</p>

</body>
</section>
</chapter>

<chapter>
<title>NX Server</title>
<section>
<title>Choosing The Correct Edition</title>
<body>

<p>
Before installing NX Server on Gentoo Linux, please make sure you have chosen
the correct edition for yourself or your organisation.  You should have
received a license key file when you purchased your license.  Hang on to that
key - you will need it shortly.
</p>

</body>
</section>
<section>
<title>Installing NX Server</title>
<body>

<p>
There are three different ebuilds in Portage, one for each of the different
editions of NX Server.  To install the correct edition, please run one of the
following commands:
</p>

<pre caption="Installing NX Server">
<comment>(for NX Server Personal Edition)</comment>
# <i>emerge -u nxserver-personal</i>
<comment>(for NX Server Small Business Edition)</comment>
# <i>emerge -u nxserver-business</i>
<comment>(for NX Server Enterprise Edition)</comment>
# <i>emerge -u nxserver-enterprise</i>
</pre>

<impo>
Make sure you install the correct edition of NX Server.  The license key that
you purchased will only work with corresponding edition of NX Server!
</impo>

<p>
Portage will automatically download, compile and install NX Server and all its
dependencies.  When Portage has finished, there will be a message on your
screen explaining any manual configuration you have to do to complete the
install.
</p>

<note>
When you install NX Server, Portage will automatically install NX Client for
you too.  NX Server relies on files installed by NX Client.  If you manually
remove NX Client in the future, your NX Server installation will stop working.
</note>

</body>
</section>
<section>
<title>Running NX Server</title>
<body>

<p>
Please refer to the documentation on the <uri link="http://www.nomachine.com">NoMachine</uri> website.
</p>

</body>
</section>
<section>
<title>Upgrading NX Server</title>
<body>

<p>
If you wish to upgrade to a later version of the <e>same edition</e> of NX Server, just run:
</p>

<pre caption="Upgrading NX Server">
<comment>(for NX Server Personal Edition)</comment>
# <i>emerge -u nxserver-personal</i>
<comment>(for NX Server Small Business Edition)</comment>
# <i>emerge -u nxserver-business</i>
<comment>(for NX Server Enterprise Edition)</comment>
# <i>emerge -u nxserver-enterprise</i>
</pre>

<p>
Portage will automatically download and install the latest available version of
your edition of NX Server for you.  If there are any manual configuration steps
required at the end of the installation, Portage will display a message telling
you what you need to do.
</p>

</body>
</section>

<section>
<title>Switching To A Different Edition Of NX Server</title>
<body>

<p>
If you wish to change from one edition of NX Server to another (for example,
from Personal to Small Business), please run the following commands:
</p>

<pre caption="Upgrading to another edition">
<i>rm -f /usr/portage/distfiles/nxserver*.rpm</i>
<i>emerge -C nxserver-personal</i>
<i>emerge -u nxserver-business</i>
</pre>

<p>
The <c>rm -f</c> step is necessary because NoMachine use identical filenames
for the RPMs for each edition of NX Server.  Unfortunately, although the
filenames are the same, the contents of the files are not.  This unusual
approach isn't compatible with Portage's checksum (and soon, signed package)
support.  If you do not <c>rm -f</c> your old NX Server RPM file, you will get
an error from Portage.
</p>

</body>
</section>
<section>
<title>Reporting Bugs About NX Server</title>
<body>

<p>
You can report bugs about NX Server on Gentoo Linux to <uri link="http://bugs.gentoo.org">our bug-tracking system</uri>.  If the bug is in
NX itself, rather than in Gentoo Linux, we can report it upstream to NoMachine
for you.
</p>

</body>
</section>
</chapter>

<chapter>
<title>NX Client</title>
<section>
<title>Installing NX Client</title>
<body>

<p>
No matter what edition of NX Server you have chosen, NX Client can talk to them
all.  To install NX Client, please run these commands:
</p>

<pre caption="Installing the client">
# <i>emerge -u nxclient</i>
# <i>env-update</i>
# <i>source /etc/profile</i>
</pre>

<p>
Portage will automatically download, compile, and install NX Client and all its
dependencies.  When Portage has finished, there will be a message on the screen
explaining any manual configuration you have to do to complete the install.
</p>

<p>
NX Client lives in <path>/usr/NX/bin</path>.  Portage automatically adds this
directory to your PATH.
</p>

</body>
</section>

<section>
<title>Using NX Client</title>
<body>

<p>
To use NX Client on Gentoo, simply run this command from your favourite xterm:
</p>

<pre caption="Running the client">
$ <i>nxclient</i>
</pre>

<p>
The dialog box that appears should be self-explanatory.  If you need any
further help, please consult the documentation on the <uri link="http://www.nomachine.com/">NoMachine</uri> website.
</p>

</body>
</section>
</chapter>

</guide>