Man Linux: Main Page and Category List

NAME

       gnuserv, gnuclient - Server and Clients for Emacs and XEmacs

SYNOPSIS

       gnuclient  [-display  display]  [-q]  [-v]  [-l  library]  [-batch] [-f
       function] [-eval form] [-h hostname]  [-p  port]  [-r  remote-pathname]
       [[+line] file] ...
       gnudoit [-q] form
       gnuserv
       gnuattach Removed as of gnuserv 3.x

DESCRIPTION

       gnuclient  allows the user to request a running Emacs or XEmacs process
       to edit the named files or  directories  and/or  evaluate  lisp  forms.
       Depending  on  your  environment,  it can be an X frame or a TTY frame.
       One typical use for this is with a dialup connection to  a  machine  on
       which an Emacs or XEmacs process is currently running.

       gnudoit  is a shell script frontend to ``gnuclient -batch -eval form''.
       Its use is deprecated. Try to get used to calling gnuclient directly.

       gnuserv is the server program that is set running by Emacs or XEmacs to
       handle  all  incoming  and outgoing requests. It is not usually invoked
       directly, but is started from Emacs or XEmacs by  loading  the  gnuserv
       package and evaluating the Lisp form (gnuserv-start).

       gnuattach no longer exists.

OPTIONS

       gnuclient  supports  as  much  of  the command line options of Emacs as
       makes sense in this context. In addition it adds a few of its own.
       Options with long names can also be specified  using  a  double  hyphen
       instead of a single one.

       -display display, --display display
               If  this  option is given or the `DISPLAY' environment variable
               is set then gnuclient will tell Emacs to edit files in a  frame
               on the specified X device.

       -q      This  option informs gnuclient to exit once connection has been
               made with the XEmacs process.  Normally gnuclient  waits  until
               all  of  the  files on the command line have been finished with
               (their buffers killed) by the XEmacs process, and all the forms
               have been evaluated.

       -v      When  this  option  is specified gnuclient will request for the
               specified files to be viewed instead of edited.

       -l library
               Tell Emacs to load the specified library.

       -batch  Tell Emacs not to open any  frames.  Just  load  libraries  and
               evaluate  lisp code.  If no files to execute, functions to call
               or forms to eval are given using the -l, -f, or -eval  options,
               then forms to eval are read from STDIN.

       -f function,
               Make Emacs execute the lisp function.

       -eval form
               Make Emacs execute the lisp form.

       -h hostname
               Used  only  with Internet-domain sockets, this option specifies
               the host machine which  should  be  running  gnuserv.  If  this
               option  is  not  specified  then  the  value of the environment
               variable GNU_HOST is used if set. If no hostname is  specified,
               and  the  GNU_HOST  variable is not set, an internet connection
               will not be attempted. N.B.: gnuserv does  NOT  allow  internet
               connections   unless   XAUTH  authentication  is  used  or  the
               GNU_SECURE variable has been specified and  points  at  a  file
               listing all trusted hosts. (See SECURITY below.)

               Note  that  an  internet  address may be specified instead of a
               hostname which can speed up connections to the server by  quite
               a bit, especially if the client machine is running YP.

               Note  also  that a hostname of unix can be used to specify that
               the connection to the server should use  a  Unix-domain  socket
               (if supported) rather than an Internet-domain socket.

       -p port Used  only  with Internet-domain sockets, this option specifies
               the  service  port  used  to  communicate  between  server  and
               clients.   If  this  option is not specified, then the value of
               the environment variable GNU_PORT is used, if set, otherwise  a
               service  called  ``gnuserv''  is  looked  up  in  the  services
               database.  Finally, if no other value  can  be  found  for  the
               port, then a default port is used which is usually 21490 + uid.
               Note that since gnuserv doesn't allow command-line options, the
               port  for  it  will  have  to  be  specified  via  one  of  the
               alternative methods.

       -r pathname
               Used only with Internet-domain sockets, the  pathname  argument
               may  be  needed to inform Emacs how to reach the root directory
               of a remote machine.  gnuclient prepends this  string  to  each
               path argument given.  For example, if you were trying to edit a
               file on a client machine called otter, whose root directory was
               accessible  from  the  server  machine via the path /net/otter,
               then this argument should be  set  to  '/net/otter'.   If  this
               option is omitted, then the value is taken from the environment
               variable GNU_NODE, if set, or the empty string otherwise.

       [+n] file
               This is the path of the file to be edited.  If the  file  is  a
               directory,  then  the  directory  browsers  dired or monkey are
               usually invoked instead.  The cursor is put at line number  'n'
               if specified.

SETUP

       gnuserv   is  packaged  standardly  with  recent  versions  of  XEmacs.
       Therefore, you should be able to start the server simply by  evaluating
       the  XEmacs  Lisp  form (gnuserv-start), or equivalently by typing `M-x
       gnuserv-start'.

CONFIGURATION

       The behavior of this suite of program is mostly controlled on the  lisp
       side  in  Emacs  and  its behavior can be customized to a large extent.
       Type `M-x customize-group  RET  gnuserv  RET'  for  easy  access.  More
       documentation can be found in the file `gnuserv.el'

EXAMPLE

           gnuclient -q -f mh-smail
           gnuclient -h cuckoo -r /ange@otter: /tmp/*
           gnuclient ../src/listproc.c

       More   examples   and  sample  wrapper  scripts  are  provided  in  the
       etc/gnuserv directory of the Emacs installation.

SYSV IPC

       SysV IPC is used to communicate between gnuclient and  gnuserv  if  the
       symbol   SYSV_IPC   is  defined  at  the  top  of  gnuserv.h.  This  is
       incompatible  with  both   Unix-domain   and   Internet-domain   socket
       communication as described below. A file called /tmp/gsrv??? is created
       as a key  for  the  message  queue,  and  if  removed  will  cause  the
       communication  between  server  and  client to fail until the server is
       restarted.

UNIX-DOMAIN SOCKETS

       A Unix-domain socket is  used  to  communicate  between  gnuclient  and
       gnuserv  if  the  symbol  UNIX_DOMAIN_SOCKETS  is defined at the top of
       gnuserv.h.   A  file  called  /tmp/gsrvdir????/gsrv  is   created   for
       communication.   If  the  symbol  USE_TMPDIR  is  set  at  the  top  of
       gnuserv.h, $TMPDIR, when set, is used instead of /tmp.  If that file is
       deleted,  or TMPDIR has different values for the server and the client,
       communication between server and  client  will  fail.   Only  the  user
       running gnuserv will be able to connect to the socket.

INTERNET-DOMAIN SOCKETS

       Internet-domain  sockets  are used to communicate between gnuclient and
       gnuserv if the symbol INTERNET_DOMAIN_SOCKETS is defined at the top  of
       gnuserv.h.  Both Internet-domain and Unix-domain sockets can be used at
       the same time. If a hostname is specified via -h or  via  the  GNU_HOST
       environment variable, gnuclient establish connections using an internet
       domain socket. If not, a local connection is  attempted  via  either  a
       unix-domain socket or SYSV IPC.

SECURITY

       Using Internet-domain sockets, a more robust form of security is needed
       that wasn't necessary with either  Unix-domain  sockets  or  SysV  IPC.
       Currently,  two authentication protocols are supported to provide this:
       MIT-MAGIC-COOKIE-1 (based on the X11 xauth(1)  program)  and  a  simple
       host-based  access  control  mechanism, hereafter called GNUSERV-1. The
       GNUSERV-1 protocol is always available, whereas support for  MIT-MAGIC-
       COOKIE-1  may or may not have been enabled (via a #define at the top of
       gnuserv.h) at compile-time.

       gnuserv, using GNUSERV-1, performs a limited form of access control  at
       the  machine level. By default no internet-domain socket is opened.  If
       the variable GNU_SECURE can be found in gnuserv's environment,  and  it
       names a readable filename, then this file is opened and assumed to be a
       list of hosts, one per line, from which the server will allow requests.
       Connections  from  any other host will be rejected. Even the machine on
       which gnuserv is running is not permitted to make connections  via  the
       internet  socket  unless  its  hostname is explicitly specified in this
       file.  Note that a host may  be  either  a  numeric  IP  address  or  a
       hostname,  and  that  any  user on an approved host may connect to your
       gnuserv and execute arbitrary elisp (e.g., delete all your files).   If
       this  file contains a lot of hostnames then the server may take quite a
       time to start up.

       When the MIT-MAGIC-COOKIE-1 protocol is enabled, an internet socket  is
       opened  by default. gnuserv will accept a connection from any host, and
       will wait  for  a  "magic  cookie"  (essentially,  a  password)  to  be
       presented  by  the client. If the client doesn't present the cookie, or
       if the cookie is wrong, the authentication of the client is  considered
       to  have  failed.  At  this  point. gnuserv falls back to the GNUSERV-1
       protocol; If the client is calling from a host listed in the GNU_SECURE
       file, the connection will be accepted, otherwise it will be rejected.

       Using MIT-MAGIC-COOKIE-1 authentication
           When  the  gnuserv server is started, it looks for a cookie defined
           for display 999 on the machine where it is running. If  the  cookie
           is  found,  it will be stored for use as the authentication cookie.
           These  cookies  are  defined  in  an  authorization  file  (usually
           ~/.Xauthority) that is manipulated by the X11 xauth(1) program. For
           example, a machine "kali" which runs an emacs that invokes  gnuserv
           should  respond  as  follows  (at  the  shell  prompt)  when set up
           correctly.

               kali% xauth list
               GS65.SP.CS.CMU.EDU:0  MIT-MAGIC-COOKIE-1  11223344
               KALI.FTM.CS.CMU.EDU:999  MIT-MAGIC-COOKIE-1  1234

           In the above case, the authorization file defines two cookies.  The
           second  one,  defined for screen 999 on the server machine, is used
           for gnuserv authentication.

           On the client machine's side, the authorization file  must  contain
           an  identical line, specifying the server's cookie. In other words,
           on a machine "foobar" which  wishes  to  connect  to  "kali,"   the
           `xauth list' output should contain the line:

               KALI.FTM.CS.CMU.EDU:999  MIT-MAGIC-COOKIE-1  1234

           To create the cookie, you can use a command like
               xauth   add   `hostname`:999   MIT-MAGIC-COOKIE-1  `head  -c512
               /dev/urandom|md5sum`

           For more information on authorization files, take  a  look  at  the
           xauth(1X11)  man  page,  or invoke xauth interactively (without any
           arguments) and type "help" at the prompt. Remember that case in the
           name  of  the  authorization protocol (i.e.`MIT-MAGIC-COOKIE-1') is
           significant!

ENVIRONMENT

       DISPLAY Default X device to put edit frame.

FILES

       /tmp/gsrv???
               (SYSV_IPC only)

       /tmp/gsrvdir???/gsrv
               (unix domain sockets only)

       ~/.emacs
               Emacs customization file, see emacs(1) and xemacs(1).

SEE ALSO

       dtemacs(1), xauth(1X11), Xsecurity(1X11), gnuserv.el

BUGS

       NULs occurring in result strings  don't  get  passed  back  to  gnudoit
       properly.

AUTHOR.

       Andy     Norman     (ange@hplb.hpl.hp.com),    based    heavily    upon
       etc/emacsclient.c, etc/server.c and lisp/server.el from the  GNU  Emacs
       18.52    distribution.    Various   modifications   from   Bob   Weiner
       (weiner@mot.com), Darrell Kindred  (dkindred@cmu.edu),  Arup  Mukherjee
       (arup@cmu.edu),   Ben   Wing   (ben@xemacs.org)   and   Hrvoje   Niksic
       (hniksic@xemacs.org).