manual: Move /var/paraslash instructions to Troubleshooting.

[paraslash.git] / web / manual.m4

diff --git a/web/manual.m4 b/web/manual.m4
index 0a5f580a79d4fbe603aa87c90c959e90b4d089ce..b7e059785b193ccb67a1c47d34a6d60143b23229 100644 (file)
--- a/web/manual.m4
+++ b/web/manual.m4
@@ -374,14 +374,6 @@ Finally, tell para_client to connect to server_host:
 
 *Step 2*: Start para_server
 
 
 *Step 2*: Start para_server
 

-Before starting the server make sure you have write permissions to
-the directory /var/paraslash that has been created during installation:
-
-       sudo chown $LOGNAME /var/paraslash
-
-Alternatively, use the --afs-socket Option to specify a different
-location for the AFS command socket.
-

 For this first try, we'll use the info loglevel to make the output
 of para_server more verbose.
 
 For this first try, we'll use the info loglevel to make the output
 of para_server more verbose.
 


@@ -426,19 +418,8 @@ You may print the list of all known audio files with
 
 *Step 4*: Configure para_audiod
 
 
 *Step 4*: Configure para_audiod
 

-para_audiod needs to create a "well-known" socket for the clients to
-connect to. The default path for this socket is
-
-       /var/paraslash/audiod_socket.$HOSTNAME
-
-In order to make this directory writable for para_audiod, execute
-as bar@client_host
-
-       sudo chown $LOGNAME /var/paraslash
-
-
-We will also have to tell para_audiod that it should receive the
-audio stream from server_host via http:
+We will have to tell para_audiod that it should receive the audio
+stream from server_host via http:

 
        para_audiod -l info -r '.:http -i server_host'
 
 
        para_audiod -l info -r '.:http -i server_host'
 


@@ -455,9 +436,16 @@ streamed in which order.
 
 *Troubleshooting*
 
 
 *Troubleshooting*
 

-It did not work? To find out why, try to receive, decode and play the
-stream manually using para_recv, para_filter and para_write as follows.
+If you receive a socket related error on server or audiod startup,
+make sure you have write permissions to the /var/paraslash directory:
+
+       sudo chown $LOGNAME /var/paraslash

 
 

+Alternatively, use the --afs-socket (para_server) or --socket
+(para_audiod) option to specify a different socket pathname.
+
+To identify streaming problems try to receive, decode and play the
+stream manually using para_recv, para_filter and para_write as follows.

 For simplicity we assume that you're running Linux/ALSA and that only
 MP3 files have been added to the database.
 
 For simplicity we assume that you're running Linux/ALSA and that only
 MP3 files have been added to the database.
 


@@ -2145,6 +2133,35 @@ maintain state for each listening receiver, multicast often implies
 connectionless transport, which is the reason that it is currently
 only available via UDP.
 
 connectionless transport, which is the reason that it is currently
 only available via UDP.
 

+Abstract socket namespace
+~~~~~~~~~~~~~~~~~~~~~~~~~
+UNIX domain sockets are a traditional way to communicate between
+processes on the same machine. They are always reliable (see above)
+and don't reorder datagrams. Unlike TCP and UDP, UNIX domain sockets
+support passing open file descriptors or process credentials to
+other processes.
+
+The usual way to set up a UNIX domain socket (as obtained from
+socket(2)) for listening is to first bind the socket to a file system
+pathname and then call listen(2), then accept(2). Such sockets are
+called _pathname sockets_ because bind(2) creates a special socket
+file at the specified path. Pathname sockets allow unrelated processes
+to communicate with the listening process by binding to the same path
+and calling connect(2).
+
+There are two problems with pathname sockets:
+
+       * The listing process must be able to (safely) create the
+       socket special in a directory which is also accessible to
+       the connecting process.
+
+       * After an unclean shutdown of the listening process, a stale
+       socket special may reside on the file system.
+
+The abstract socket namespace is a non-portable Linux feature which
+avoids these problems. Abstract sockets are still bound to a name,
+but the name has no connection with file system pathnames.
+

 License
 ~~~~~~~
 
 License
 ~~~~~~~