[Zope3-checkins] CVS: Zope3/doc - FAQ.txt:1.12
Guido van Rossum
guido@python.org
Fri, 9 Aug 2002 12:44:55 -0400
Update of /cvs-repository/Zope3/doc
In directory cvs.zope.org:/tmp/cvs-serv22656
Modified Files:
FAQ.txt
Log Message:
This was mostly for Zope2.
=== Zope3/doc/FAQ.txt 1.11 => 1.12 ===
--- Zope3/doc/FAQ.txt:1.11 Tue Feb 5 10:29:43 2002
+++ Zope3/doc/FAQ.txt Fri Aug 9 12:44:54 2002
@@ -1,227 +1,2 @@
Zope Installation Frequently Asked Questions
--------------------------------------------
-
- Installing Zope
-
- 1. On certain Unix platforms (usually Solaris) I get a "checksum
- error" untarring the Zope distribution. Whats the deal?
-
- Zope is built and distributed using GNU tar. Some vendor-supplied
- tar implementations have problems with long path names as they
- appear in GNU tar created files. This is a problem that occurs in
- a number of software distributions created using GNU tar, not just
- Zope. We suggest that you install a GNU tar on your system to
- avoid this problem (not just with Zope, but with other software
- distributions as well).
-
- 2. I am trying to build Zope on my BSD based system, but I
- keep getting "symbol not found" errors and the build
- scripts stop. What do I do?
-
- On some BSD based systems (BSDI, BSD/OS), you need to edit
- the Makefile.pre.in files in your Zope installation to add
- -rdynamic to the LDSHARED makefile variable. On some systems
- it may also be necessary to change the file named 'do.py'
- located in the 'inst' directory of your Zope installation,
- changing the line: do('make') to: do('make -k').
-
- 3. I am having trouble building Zope on my OpenBSD system. I get
- some wierd compilation errors.
-
- Make sure you unpack Zope using GNU tar; you will not get any
- error messages with OpenBSD's standard tar, but your installation
- will be subtly broken due to problems with long path names.
-
- 4. I am having trouble building Zope on a libc 5 Linux machine.
-
- Zope requires Python be built with glibc 2.x (libc 6) on Linux.
-
- 5. I am trying to install Zope on a Windows NT/2000 machine, but
- I keep getting a dialog saying "corrupt installation detected".
- Is something wrong with the distribution file?
-
- No, to install Windows NT / 2000 you should be logged in with
- "Administrator" privileges on the machine. If you are seeing
- the "corrupt installation detected" dialog, you probably don't
- have the required administrator privileges (your guess is as
- good as ours as to why you get that particular error message).
-
-
- Starting/Accessing your Zope installation
-
- 1. After installing Zope, I go to the URL in my web browser
- but I get a "404 Not Found" or "Server Error" message
-
- This message is coming from your web server, not Zope.
- It usually means that your web server is misconfigured.
- Ensure that the PCGI info file generated by the installation
- procedure exists in a cgi-enabled directory, and that your
- web server has any required aliases or configuration options
- set to enable it to find this file and run it as a cgi program.
-
- Look in the error log for your web server for details of the error.
-
-
- 2. I have installed Zope, and when I go to the URL in my web
- browser, I get a password prompt. Although I type in the correct
- username and password, I keep getting prompted. What is going on?
-
- Zope manages access control internally, but it relies on your
- web server software to relay any authentication information in
- web requests. Some web servers automatically filter this information
- out of requests passed to cgi programs. If you keep getting password
- prompts that never accept your password, this means that your web
- server is not properly configured to pass authentication info on to
- Zope. See the doc/WEBVSERVER.txt file for information on correctly
- configuring your web server to pass authentication information.
-
-
- 3. I have installed Zope, and when I go to the URL in my web
- browser, I get a screen that says "Temporarily Unavailable".
-
- Try the URL again - if you still get "Temporarily Unavailable",
- this means that your PCGI resource file was unable to start
- the Zope process. This usually means either an error in the
- PCGI resource file, or a problem with your Zope installation
- such as incorrect permissions on certain directories.
-
- You should always run the install script to ensure that a
- correct PCGI resource file is generated. If you have changed
- this file by hand, ensure that all of the pathnames in the file
- are valid and that there are no typos.
-
- The install script should also ensure correct ownership and permissions
- on files and directories in your Zope installation. The var
- subdirectory of your installation and everything therein MUST be
- writable by the user which runs cgi scripts on your web server
- (usually nobody if you are using PCGI.)
-
- If you have ensured that the PCGI info file is correct and that all
- permissions are correct, you can look in the /var/tmp directory of
- your machine for files with names like "pcgi.110407". If PCGI fails
- to start the Zope process, it will attempt to write a file
- named pcgi.HHMMSS to /var/tmp containing information which may be
- useful in determining the error.
-
- On Windows NT platforms, check the event log under "Application Log"
- for error information.
-
- Additionally, if you receive a "Temporarily Unavailable", look at
- the document source for an HTML comment with error information.
-
-
- 4. When I go to a URL for an application that isn't running, it
- takes quite a while to startup. Why is that?
-
- The *PCGI wrapper*, which is the executable run as a CGI script
- on every request, has quite a bit of thinking to do. First, it
- has to see if the app is already running. If not, it has to see
- if any other PCGI wrappers have already started the app. It is
- this latter part where some of the delay presents itself.
-
- Next, the application itself has to get into memory and then get
- the database loaded. Depending on database file size, this might
- take a while. Packing your Zope database at regular intervals
- can reduce startup time.
-
-
- 5. I have Zope with the Oracle Database adapter installed, and can't
- get it running. Why?
-
- If you have Oracle installed, you need to ensure that the
- environment variable "ORACLE_HOME" is in the environment of
- the running application. You can do this by adding a line to
- your PCGI resource file such as: ORACLE_HOME=/usr/bin/oracle
-
- Any NAME=VALUE pairs appended to the PCGI resource file will
- be added to the environment of the process when it is started
- by PCGI.
-
- 6. I have forgotten the only password used to access the site or
- I have modified the security settings in such a way that even
- I can't get access. How do I fix it?
-
- Assuming you have write access to the directory where Zope is
- installed, you can create a temporary "emergency user" using
- the 'zpasswd.py' script::
-
- python zpasswd.py access
-
- Follow the prompts to enter a user name and password.
- 'zpasswd.py' will write the file named 'access'. Zope will
- look for this file the next time it starts. After restarting,
- browse to Zope's management interface and use the name and
- password you entered.
-
- As the emergency user, you are allowed to create user folders
- and user accounts as well as adjust security settings but you
- are not allowed to create objects like DTML methods or folders.
- This is a safety precaution.
-
- See more details in the file SECURITY.TXT.
-
- Managing the Zope process
-
- 1. How do I find the application server in my process listing?
-
- Whether running Zope with ZServer (yay) or straight PCGI (not
- so yay), or there will be a .pid file in var with the pid of the
- process. For ZServer, the pid file is named 'z2.pid' (and it
- contains two pids). For PCGI, the file will be 'pcgi.pid'.
-
- 2. If I have more than one Zope process running on the same
- machine, how do I tell them apart in "ps" listings?
-
- When running under ZServer, the Zope processes will show up in
- the listings with 'z2.py'. (You may need to do a long listing
- to see it.) PCGI mastered zopes will have 'pcgi-wrapper'.
-
- 3. What files are used by the object database?
-
- The state of the application is stored in files in the 'var'
- subdirectory inside the installation. There is currently one
- file:
-
- o Data.fs -- Primary database file
-
- Data.fs replaces the database file of prior versions,
- Data.bbb. To convert an existing Data.bbb file to the new
- format, see doc/ZODB.txt.
-
- Other files in the 'var' directory are associated with each
- process and are only temporary.
-
-
- 4. Is it OK to use 'kill' to shutdown the process?
-
- It is best to shutdown the process using the Shutdown button in
- the Control Panel. Alternatively, the URL:
-
- 'Control_Panel/manage_shutdown'
-
- will, with a suitable username and password, shutdown the
- application. If you need a non-interactive way to shutdown your
- application, e.g. from a script, then write a program that sends
- a web request to that URL with the appropriate username and
- password.
-
- If you must, you can shutdown the application by killing it.
- The respective var/*.pid file will have the pids - for ZServer
- (yay) it's var/z2.pid, for pcgi (not so yay), it's
- var/pcgi.pid.
-
- General
-
-
- 1. My browser is giving a message, 'Sorry, an error occurred.'
- How do I find out what the real error is?
-
- Step number one in these scenarios is to view the HTML source of
- the frame containing the error. In general, the *traceback* of
- the error message is enclosed in an HTML comment. This
- traceback explains the error message.
-
- Occassionally you won't see the error message. Rather, the HTML
- source will contain the last good HTML returned by the request
- before the error occurred. This is due to caching by the
- browser. Clear your cache and view the HTML source again.