Menu
▾
▴
[Firebird-checkins] CVS: manual/src/docs/firebirddocs quickstartguide-2.xml, 1.2, 1.3
|
From: Paul V. <pau...@us...> - 2006-05-31 13:39:32
|
Update of /cvsroot/firebird/manual/src/docs/firebirddocs In directory sc8-pr-cvs5.sourceforge.net:/tmp/cvs-serv14658/src/docs/firebirddocs Modified Files: quickstartguide-2.xml Log Message: Many changes related to Guardian and Control Panel applets Index: quickstartguide-2.xml =================================================================== RCS file: /cvsroot/firebird/manual/src/docs/firebirddocs/quickstartguide-2.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -b -U3 -r1.2 -r1.3 --- quickstartguide-2.xml 21 May 2006 15:20:40 -0000 1.2 +++ quickstartguide-2.xml 31 May 2006 13:39:23 -0000 1.3 @@ -23,21 +23,14 @@ <section id="qsg2-about"> <title>About this guide</title> - <!--TODO : did Paul Reeves fix the Control Panel Applet?--> - - <para>This guide is an introduction for the complete newcomer to a few - essentials for getting off to a quick start with a Firebird binary kit. - For the fine details of configuring and running your server and tuning - your installation, please refer to Chapters 4-6 of the <citetitle>Using - Firebird</citetitle> manual, distributed on the <ulink - url="http://www.ibphoenix.com/main.nfs?a=ibphoenix&page=ibp_cd">IBPhoenix - CD</ulink>.</para> - - <para>The <citetitle>Firebird Quick Start Guide</citetitle> started life - as Chapter 1 of the <citetitle>Using Firebird</citetitle> manual, sold on - CD by <ulink url="http://www.ibphoenix.com">IBPhoenix</ulink>. Later it - was published separately on the Internet. In June 2004, IBPhoenix donated - the guide to the Firebird Project.</para> + <para>The <citetitle>Firebird Quick Start Guide</citetitle> is an + introduction for the complete newcomer to a few essentials for getting off + to a quick start with a Firebird binary kit. The guide started life as + Chapter 1 of the <citetitle>Using Firebird</citetitle> manual, sold on CD + by <ulink url="http://www.ibphoenix.com">IBPhoenix</ulink>. Later it was + published separately on the Internet. In June 2004, IBPhoenix donated the + guide to the Firebird Project. Since then it is maintained, and regularly + updated, by members of the Firebird documentation project.</para> <important> <para>Before you read on, verify that your Firebird version matches this @@ -66,7 +59,7 @@ </listitem> <listitem> - <para>A client library located on the server machine.</para> + <para>On or more client libraries.</para> </listitem> <listitem> @@ -82,7 +75,7 @@ </listitem> <listitem> - <para>The C header files (not needed by beginners!)</para> + <para>The C header files (not needed by beginners).</para> </listitem> <listitem> @@ -108,7 +101,7 @@ overview of the most important differences follows.</para> <table> - <title>Firebird 1.5 Classic Server vs. Superserver</title> + <title>Firebird 2 Classic Server vs. Superserver</title> <tgroup cols="2"> <colspec colname="col-classic" colwidth="*" /> @@ -129,10 +122,9 @@ connection, each with its own cache. Less resource use if the number of connections is low.</para></entry> - <entry><!--As per correction Alex Peshkov on admin list 8 Dec 2005.--><para>A - single process serves all the connections, using threads to handle - requests. Shared cache space. More efficient if the number of - simultaneous connections grows.</para></entry> + <entry><para>A single process serves all the connections, using + threads to handle requests. Shared cache space. More efficient if + the number of simultaneous connections grows.</para></entry> </row> <row valign="top"> @@ -145,8 +137,7 @@ via <systemitem class="systemname">localhost</systemitem> (often implicitly). On Windows, this is optional; you can also make direct local connections, but these are not as fast as the - <quote>Classic</quote> ones on Linux and also less - safe.</para></entry> + <quote>Classic</quote> ones on Linux and also less safe.<!--Still less safe, what with XNET and so?--></para></entry> </row> <row valign="top"> @@ -161,6 +152,17 @@ configuration file <filename>firebird.conf</filename>.</para></entry> </row> + + <row> + <entry><!--REMOVE ROW IF BUG FIXED BEFORE 2.0 FINAL--><para>When + run as a Windows <emphasis>application</emphasis> (as opposed to a + service) you can't use the Firebird Guardian. Note that running + Firebird as an application is the only option on Windows + 9xâME.</para></entry> + + <entry><para>Can be used with the Guardian on Windows, whether run + as an application or as a service.</para></entry> + </row> </tbody> </tgroup> </table> @@ -208,15 +210,6 @@ <para>The following table describes the default disk locations for the components on Windows and Linux.</para> - <para>In the major codebase revision starting at v.1.5, the old hard links - to InterBase artifacts were removed and many of the major components were - renamed. As a result, Firebird 1.5 and higher permit a running InterBase® - server to be present, provided the two servers don't listen on the same - TCP/IP port. If you need this feature, read <citetitle>Configuring the - port service</citetitle> in the Release Notes that came with your Firebird - installation (look in the <filename class="directory">doc</filename> - subdir).</para> - <table frame="all" id="qsg2-tbl-firebird-components" xreflabel="Firebird installation components table"> <title>Components of the Firebird 2 installation</title> @@ -471,50 +464,68 @@ </indexterm>Installation script or program</title> <para>Although it is possible to install Firebird by a filesystem - copying method â such as <quote>untarring</quote> a snapshot build - file or decompressing a structured WinZip <filename - class="extension">.zip</filename> file â it is strongly recommended - that you use the distributed release kit the first time you install - Firebird. The Windows executable installation script, the Linux - <application>rpm</application> (<application><citetitle>RPM Package - Manager</citetitle>, originally <citetitle>RedHat Package - Manager</citetitle></application>) program and the official <filename - class="extension">.tar.gz</filename> for other Posix platforms perform - some essential setup tasks. Provided you follow the instructions - correctly, there should be nothing for you to do upon completion but - log in and go!</para> + copying method â such as <quote>untarring</quote> a snapshot build or + decompressing a structured <filename class="extension">.zip</filename> + archive â it is strongly recommended that you use the distributed + release kit (<filename>.exe</filename> for Windows, + <filename>.rpm</filename> for Linux), especially if this is the first + time you install Firebird. The Windows installation executable, the + Linux <application>rpm</application> program and the + <filename>install.sh</filename> script in the official <filename + class="extension">.tar.gz</filename> for various Posix platforms all + perform some essential setup tasks. Provided you follow the + instructions correctly, there should be nothing for you to do upon + completion but log in and go!</para> <section> <title>Windows platforms</title> <para>The Firebird installer lets you choose between Superserver and Classic Server installation. Both are fully mature and stable and - there are no reasons to categorically prefer one to the other. You - may have your own specific reasons of course.</para> + there are no reasons to categorically prefer one to the other. Of + course you may have your own specific reasons.</para> <para>If you install Firebird under Windows 95/98/ME, <emphasis role="bold">un</emphasis>check the option to install the Control Panel applet. It doesn't work on these platforms. We'll give you a - link to a usable applet later on in this guide.</para> + link to a usable applet later on in this guide. (Note: the option to + install the applet is only available for Superserver.)</para> - <para>On server platforms â Windows NT, 2000 and XP â the Firebird - service will be running when the installation completes. Next time - you boot up your server machine, it will be started - automatically.</para> + <para>On Windows server platforms â NT, 2000, 2003 and XP â Firebird + wil run as a system service be default, but during the installation + you can also choose to let it run as an application. Non-server + Windows systems â 95, 98 and ME â don't support services; running as + an application is the only option there.</para> + </section> - <para><indexterm> + <section> + <title><indexterm> <primary>Guardian</primary> - </indexterm>The non-server Windows platforms â Windows 95, 98 and - ME â do not support services. The installation will start Firebird - server as an application, protected by another application known as - the Guardian. If the server application should terminate abnormally - for some reason, the Guardian will attempt to restart it.</para> + </indexterm>Use the Guardian?</title> - <!--Does Classic install with Guardian too?--> + <!--CHANGE/REMOVE THIS PARA IF BUG FIXED BEFIRE FIREBIRD 2 FINAL--> + + <para>The Firebird Guardian is a utility that monitors the server + process and tries to restart it if it terminates abnormally. Due to + a bug, the Guardian does not work with Firebird Classic if run as an + application. So, if you choose to run (or must run) Firebird Classic + as an application, make sure to uncheck the box labeled <quote>Use + the Guardian</quote> during the installation dialog.</para> + + <para>The Guardian works correctly with Superserver, whether run as + an application or as a service.</para> + + <para>If you run Firebird <emphasis>as a service</emphasis> on + Windows 2000, 2003 or XP, the Guardian is a convenience rather than + a necessity, since these operating systems have the facility to + watch and restart services. It is recommended that you keep the + Guardian option on in all other situations.</para> + + <!--...except where the abovementioned bug keeps it from working correctly (if applicable)--> </section> <section> - <title>Posix platforms</title> + <title>Linux and other Unix-like platforms</title> <para>In all cases, read the release notes that pertain to the version of Firebird that you are going to install. There may be @@ -584,13 +595,6 @@ <para>substituting this example IP address for the IP address that your server is broadcasting.</para> - <warning> - <para>If you get a timeout message, study the <citetitle>Using - Firebird</citetitle> manual â Chapter 6: <citetitle>Network - Configuration</citetitle>, and Chapter 7: <citetitle>Troubleshooting - Connections</citetitle> â for further instructions.</para> - </warning> - <para>Note that if you are connecting to the server from a local client â that is, a client running on the same machine as the server â you can ping the virtual TCP/IP loopback server:</para> @@ -599,6 +603,9 @@ <para><command>ping localhost</command> âorâ <command>ping 127.0.0.1</command></para> </blockquote> + + <para>If the server machine is reachable from the client, you can go + on to the next step.</para> </section> <section> @@ -606,11 +613,82 @@ <primary>Checking the server</primary> </indexterm>Checking that the Firebird server is running</title> - <para>After installation, Firebird server should be running as a - service on Windows NT, 2000 or XP or on Linux.</para> + <para>After installation, Firebird server should be running:</para> + + <variablelist> + <varlistentry> + <term>On Linux or other Unix-like systems</term> + + <listitem> + <para>As a service.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>On Windows server systems (NT, 2000, 2003, XP)</term> + + <listitem> + <para>As a service or as an application. Service is default and + highly recommended.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>On Windows non-server systems (95, 98, ME)</term> + + <listitem> + <para>As an application.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The following sections show you how to test the server in each + of these situations.</para> + + <section> + <title>Server check: Linux and other Unices</title> + + <para><indexterm> + <primary>top command (Linux)</primary> + </indexterm><indexterm> + <primary>Guardian</primary> + </indexterm>Use the <command>top</command> command in a command + shell to inspect the running processes interactively. If a Firebird + Superserver is running, you should see a process named + <application><systemitem>fbguard</systemitem></application>. This is + the Guardian process. Further, there will be one main and zero or + more child processes named + <application><systemitem>fbserver</systemitem></application>.</para> + + <para>For Classic Server versions, the process name is + <application><systemitem>fb_inet_server</systemitem></application>. + There will be one instance of this process running for each network + connection. Note that if there are no active connections, or if + there are only direct local connections, you won't find + <application><systemitem>fb_inet_server</systemitem></application> + in the process list.</para> + + <para>The following screen shows the output of + <application>top</application>, restricted by + <application>grep</application> to show only lines containing the + characters <literal>fb</literal>:</para> + + <screen>frodo:/inkomend/firebird # top -b -n1 | grep fb + 2587 firebird 24 0 1232 1232 1028 S 0.0 0.3 0:00.00 fbguard + 2588 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.04 fbserver + 2589 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.00 fbserver + 2604 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.00 fbserver + 2605 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.02 fbserver + 2606 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.00 fbserver + 2607 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.00 fbserver</screen> + + <para>As an alternative to <application>top</application>, you can + use <command>ps -ax</command> or <command>ps -aux</command> and pipe + the output to <application>grep</application>.</para> + </section> <section> - <title>Windows NT4, 2000 and XP</title> + <title>Server check: Windows, running as service</title> <para>Open Control Panel -> Services (NT) or Control Panel -> Administrative Tools -> Services (2000, XP).</para> @@ -619,7 +697,8 @@ <primary>Services (Windows)</primary> </indexterm>This illustration shows the Services applet display on Windows 2000. The appearance may vary from one Windows server - edition to another.</para> + edition to another. Also, service names may vary with the Firebird + version.</para> <mediaobject> <imageobject> @@ -628,154 +707,185 @@ </imageobject> </mediaobject> - <para><indexterm> - <primary>Guardian</primary> - </indexterm>If the Guardian is running (as shown in the - screenshot, over) it may have a different service name because of - version changes.</para> - - <!--Is the Guardian installed by default AT ALL on WinNT-line systems? Maybe take a new screenshot. -Maybe also update note below.--> + <!--Maybe take a new screenshot.--> - <note> - <para>On Windows 2000 and XP, the Guardian is a convenience rather - than a necessity, since these two operating systems have the - facility to watch and restart services. It is recommended that you - keep Guardian active for other platforms if a SYSDBA is not - available to restart the server manually in the event that it is - stopped for some reason.</para> - </note> + <para>You should at least find the Firebird server in the services + listing. The Guardian may or may not be running, depending on the + choices you made during installation.</para> </section> <section> - <title>Windows 9x or ME</title> + <title>Server check: Windows, running as application</title> - <para><indexterm> - <primary>Guardian</primary> - </indexterm>On Windows 9x or ME Firebird server should be running - as an application, monitored by the Guardian. The Guardian's icon - should appear in the tray with a green graphic. If the icon is - flashing or showing as a red graphic, it indicates that Guardian is - either attempting to start the server or has failed.</para> + <!--Rewrite this depending on whether Paul Reeves fixes the problem that Guardian fails to start a Classic +server if run as an application.--> - <para>If you used an installation kit that installed but did not - automatically start the Guardian and the Firebird server, you can - set it up as follows:</para> + <para>If Firebird is up and running as an application, it is + represented by an icon in the system tray:</para> - <orderedlist> + <itemizedlist spacing="compact"> <listitem> - <para>Locate the executable file for the Guardian program - (<filename>fbguard.exe</filename>) and create a shortcut for it - in the Startup area of your machine's Start Menu.</para> + <para>A green and gray server symbol if controlled by the + Guardian;</para> </listitem> <listitem> - <para>Open the Properties dialog of the shortcut and go to the - field where the command line is.</para> + <para>A round yellow and black graphic if running + standalone.</para> </listitem> + </itemizedlist> - <listitem> - <para>Edit the command line so it reads as follows:</para> + <para>In either case you can shut the server down by using the menu + that appears if you right-click on the tray icon. Note that this + also makes the icon disappear; you can restart Firebird via the + Start menu.<!--IN ALL 1.5.X VERSIONS, SHUTTING DOWN CLASSIC *WITH GUARDIAN* VIA TRAY DOES *NOT* WORK. MUST KILL VIA TASK LIST.--></para> + + <para>A flashing icon indicates that the server is in the process of + starting up (or at least trying to do so). A red icon, or an icon + with a overlying red stop symbol, indicates that startup has + failed.</para> + + <para>One way to make 100% sure if the server is running or not is + to press Ctrl-Alt-Del and look for the <systemitem + class="process">fbserver</systemitem> or <systemitem + class="process">fb_inet_server</systemitem> process (and possibly + <systemitem class="process">fbguard</systemitem>) in the task + list.</para> + + <para>On some occasions, you may need to start the Guardian or + server once explicitly via the Start menu even if you opted for + <quote>Start Firebird now</quote> at the end of the installation + process. Sometimes a reboot is necessary.</para> + + <!--REMOVE FOLLOWING PARA IF BUG FIXED BEFORE FIREBIRD 2 FINAL--> + + <para>If you're desperately trying to start Firebird and nothing + seems to work, ask yourself if you've installed Firebird 2 Classic + server with the Guardian option enabled. As said before, this + combination doesn't work if Firebird runs as an application. + Uninstall Firebird if necessary and reinstall Classic + <emphasis>without</emphasis> Guardian, or Superserver with or + without Guardian.</para> - <blockquote> - <para><literal><command>fbguard.exe -a</command></literal> - (for Superserver)</para> + <para>In the case of Superserver you can also use a Control Panel + applet to check and alter the Firebird server status.</para> + </section> - <para><literal><command>fbguard.exe -c</command></literal> - (for Classic Server)</para> - </blockquote> - </listitem> + <section> + <title><indexterm> + <primary>Control Panel applets</primary> + </indexterm>Windows Control Panel applets</title> + + <para>Several control panel applets are available for use with + Firebird. Whilst such applets are not essential, they do provide a + convenient way to start and stop the server and check its current + status.</para> + + <section> + <title>Firebird Server Manager</title> + + <para>The Firebird Server Manager applet is included in the + Firebird distribution. The option to install this applet is only + available for Superserver.</para> + <note> + <para>The applet is also usable for Classic server, provided + that it (the server) runs a a service, not as an application. + Since the installation screen won't give you the option to + include the applet with a Classic server, you must, if you + really want it:</para> + + <itemizedlist spacing="compact"> <listitem> - <para>Save and close the Properties dialog.</para> + <para>Install Superserver first;</para> </listitem> <listitem> - <para>Double-click on the shortcut to start the Guardian. The - Guardian will proceed to start <filename>fbserver.exe</filename> - or <filename>fb_inet_server.exe</filename>.</para> + <para>Copy the applet + <filename>Firebird2Control.cpl</filename> from the Windows + system folder to a safe place;</para> </listitem> - </orderedlist> - <para>The Guardian should start up automatically next time you boot - your Windows 9x or ME machine.</para> + <listitem> + <para>Uninstall Superserver;</para> + </listitem> - <para>Alternatively, you can use a Control Panel applet to control - the starting and stopping of the Firebird server.</para> - </section> + <listitem> + <para>Install Classic;</para> + </listitem> - <section> - <title><indexterm> - <primary>Control Panel applets</primary> - </indexterm>Windows Control Panel applets</title> + <listitem> + <para>Copy the applet back to the system directory.</para> + </listitem> + </itemizedlist> + </note> - <para>Since version 1.0.3, a control panel applet is included in the - Firebird distribution. Whilst the applet is not essential, it does - provide a convenient way to start and stop the server.<!--Does it work with Fb 2? New screenshot?--></para> + <para>This is a screenshot of the activated applet. Note that the + title bar says <quote>Firebird Server Control</quote>, although it + is listed in the Control Panel as <citetitle>Firebird 2.0 Server + Manager</citetitle>.</para> <mediaobject> <imageobject> <imagedata align="center" - fileref="images/FbServerControl-1.5.png" format="PNG" /> + fileref="images/FbServerControl-2.png" format="PNG" /> </imageobject> </mediaobject> <para>Unfortunately, the bundled applet only works on Windows NT, - 2000 and XP. On Windows 9x and ME, if you want a handy applet like - this, visit this webpage:</para> + 2000/2003 and XP.</para> - <blockquote> - <para><ulink - url="http://www.achim-kalwa.de/fbcc.phtml">http://www.achim-kalwa.de/fbcc.phtml</ulink></para> - </blockquote> + <!--REMOVE WARNING IF BUG FIXED BEFORE FB 2 FINAL RELEASE--> - <para>and download the Firebird Control Center <ulink - url="http://www.achim-kalwa.de/dl/fbcc-0.2.6.exe">fbcc-0.2.6.exe</ulink>.</para> + <warning> + <title>Windows XP alert</title> - <para>This applet looks different from the above screenshot, but - offers the same functionality.</para> + <para>At the time of this writing (RC2 stage, May 2006) the + applet that ships with Firebird 2 will not function on most XP + systems because it needs a certain Microsoft DLL that often + isn't present. No error messages will appear, but the applet + simply won't show up in the Control Panel and won't respond if + you start it from the Explorer.</para> + + <para>To get it to work, get hold of a copy of <filename + class="libraryfile">mfc71.dll</filename> and place it in your + Windows System32 directory. Alternatively, you can take the + applet that came with Firebird 1.5 and use that one â it works + fine with Firebird 2. The applet filename is + <filename>Firebird2Control.cpl</filename> both in Firebird 1.5 + and Firebird 2. Or use the Firebird Control Center, see + below.</para> + + <para>This problem may be fixed in later versions.</para> + </warning> </section> <section> - <title>Posix servers</title> + <title>Firebird Control Center</title> - <para><indexterm> - <primary>top command (Linux)</primary> - </indexterm><indexterm> - <primary>Guardian</primary> - </indexterm>Use the <command>top</command> command in a command - shell to inspect the running processes interactively. If a Firebird - Superserver is running, you should see a process named - <application><systemitem>fbguard</systemitem></application>. This is - the Guardian process. Further, there will be one main and zero or - more child processes named - <application><systemitem>fbserver</systemitem></application>.</para> - - <para>For Classic Server versions, the process name is - <application><systemitem>fb_inet_server</systemitem></application>. - There will be one instance of this process running for each network - connection. Note that if there are no active connections, or if - there are only direct local connections, you won't find - <application><systemitem>fb_inet_server</systemitem></application> - in the process list.</para> + <para>If you want a working applet for Windows 9x or ME, visit + this webpage:</para> - <para>The following screen shows the output of - <application>top</application>, restricted by - <application>grep</application> to show only processes with names - starting with the characters <literal>fb</literal>:</para> - - <screen>frodo:/inkomend/firebird # top -b -n1 | grep fb - 2587 firebird 24 0 1232 1232 1028 S 0.0 0.3 0:00.00 fbguard - 2588 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.04 fbserver - 2589 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.00 fbserver - 2604 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.00 fbserver - 2605 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.02 fbserver - 2606 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.00 fbserver - 2607 firebird 15 0 4124 4120 2092 S 0.0 0.9 0:00.00 fbserver</screen> + <blockquote> + <para><ulink + url="http://www.achim-kalwa.de/fbcc.phtml">http://www.achim-kalwa.de/fbcc.phtml</ulink></para> + </blockquote> - <para>As an alternative to <application>top</application>, you can - use <command>ps -ax</command> or <command>ps -aux</command> and pipe - the output to <application>grep</application>.</para> + <para>and download the Firebird Control Center <ulink + url="http://www.achim-kalwa.de/dl/fbcc-0.2.7.exe">fbcc-0.2.7.exe</ulink>. + Please note that, unlike the applet included with Firebird, the + Firebird Control Center will <emphasis>not</emphasis> work with + Classic servers at all!</para> + + <para>The Control Center looks a lot different than the Firebird + applet shown in the screenshot, but offers the same functionality. + Attention Windows XP users: the button for starting and stopping + the server will be labeled <quote>Start</quote> all the time, even + when the server is already running. It functions as it should + though. On other Windowses the button will say + <quote>Start</quote> or <quote>Stop</quote> according to the + situation.</para> + </section> </section> </section> </section> @@ -1130,6 +1240,18 @@ </procedure> </section> </section> + + <section id="qsg2-installing-multiple"> + <title>Installing multiple servers</title> + + <para>Firebird 2 allows the operation of multiple servers on a single + machine. It can also run concurrenty with Firebird 1.x or InterBase + servers. Setting this up is not a beginner's task however! If you need + to run multiple servers, consult the <citetitle>Installation + Notes</citetitle> chapter of the Release Notes, and have the Firebird + 1.5 Release Notes handy too â you will be directed to them at a certain + point during your reading of the Installation Notes.</para> + </section> </section> <section id="qsg2-databases"> |