home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 14 Text / 14-Text.zip / machdocs.zip / netmsg2 < prev    next >
Internet Message Format  |  1993-02-26  |  30KB

  1. From Pa.dec.com!nobody Thu Feb 25 20:15:42 1993
  2. Return-Path: <Pa.dec.com!nobody>
  3. Received: by ukelele.GCR.COM (Smail3.1.28.1 #1)
  4.     id m0nRtfx-0001S1a; Thu, 25 Feb 93 20:15 EST
  5. Received: from inet-gw-2.pa.dec.com by uu5.psi.com (5.65b/4.0.071791-PSI/PSINet) via SMTP;
  6.         id AA01593 for spj@ukelele.GCR.COM; Thu, 25 Feb 93 19:09:37 -0500
  7. Received: by inet-gw-2.pa.dec.com; id AA28434; Thu, 25 Feb 93 16:09:40 -0800
  8. Date: Thu, 25 Feb 93 16:09:40 -0800
  9. Message-Id: <9302260009.AA28434@inet-gw-2.pa.dec.com>
  10. From: "ftpmail service on inet-gw-2.pa.dec.com" <nobody@Pa.dec.com>
  11. To: spj@ukelele.GCR.COM
  12. Subject: part 002 of /.0/Mach/doc/netmsgserver.doc (@gatekeeper.dec.com) [Mach Dox] (ascii, last)
  13. X-Complaints-To: ftpmail-admin@inet-gw-2.pa.dec.com
  14. X-Service-Address: ftpmail@inet-gw-2.pa.dec.com
  15. X-Job-Number: 730680718.24209
  16. Precedence: bulk
  17. Reply-To: <nobody@inet-gw-2.pa.dec.com>
  18. Content-Type: text
  19. Content-Length: 29231
  20. Status: O
  21.  
  22. senders then the checkups module can deallocate send rights to the
  23. corresponding local port and destroy the associated port record.
  24.  
  25.  
  26. In addition the checkups module is responsible for handling hints
  27. received saying that a remote network server has just restarted.  For
  28. such a hint the checkups module calls the port search module for each
  29. port that had the restarted network server as its owner or receiver.
  30.  
  31.  
  32.  
  33. 8.2.   Interface
  34.  
  35.  
  36.  
  37.    boolean_t  pc_init()
  38.  
  39.  
  40.  
  41. initializes  the  checkups  module.
  42.  
  43.  
  44.  
  45.    int  pc_do_checkups()
  46.  
  47.  
  48.  
  49. is called by the timer module to perform a checkup.
  50.  
  51.  
  52.  
  53.    pc_handle_checkup_request(request,from,broadcast,crypt_level)
  54.  
  55.  
  56.  
  57. is called by disp_indata_simple to handle an incoming checkup request.
  58.  
  59.  
  60.  
  61.                   24
  62.  
  63.  
  64.    pc_handle_checkup_reply(client_id,reply,from,broadcast,crypt_level)
  65.  
  66.  
  67.  
  68. is called by disp_rr_simple to handle an incoming checkup reply.
  69.  
  70.  
  71.  
  72.    void  pc_send_startup_hint()
  73.  
  74.  
  75.  
  76. is called on start-up to send out a hint saying that this network
  77. server has just restarted.
  78.  
  79.  
  80.  
  81.    int  pc_handle_startup_hint(hint,from,broadcast,crypt_level)
  82.  
  83.  
  84. is called by disp_indata_simple to handle an incoming network server
  85. restart hint.
  86.  
  87.  
  88.  
  89. 9.   Port Search
  90.  
  91.  
  92.  
  93. 9.1.   Description
  94.  
  95.  
  96.  
  97. The port search module is called when some other module (probably
  98. either the port checkups module or the IPC module) determines that the
  99. information held about a network port is no longer correct.  The task
  100. of the port search module is to update that information, in particular
  101. it may determine that the network port is dead.
  102.  
  103.  
  104. The  search  procedure  is  basically  as  follows:
  105.  
  106.  
  107.  
  108.        query  network server  believed  to  be  the  receiver;
  109.        if  receiver responds  with  useful  information
  110.        then  believe it
  111.        else {
  112.              query  network  server  believed  to  be  the  owner;
  113.              if  owner  responds  with  useful  information
  114.              then  believe  it
  115.              else  broadcast  a  request  for  information
  116.        }
  117.  
  118.  
  119.  
  120. The response to a port search query can be one of:
  121.  
  122.  
  123.  
  124.     o port here, in which case the port search concludes successfully;
  125.  
  126.     o port here but receive or ownership transferred, in which case
  127.       the port search concludes successfully with the port record
  128.       updated to reflect the new owner or receiver;
  129.  
  130.     o port not here but receive and ownership rights transferred, in
  131.       which case the port search continues by querying the new
  132.       receiver;
  133.  
  134.     o port dead, in which case the port search concludes and the port
  135.       is destroyed locally; or
  136.  
  137.     o port not known, in which case the port search continues by
  138.       resorting to a broadcast query.
  139.  
  140.  
  141.                   25
  142.  
  143.  
  144. In addition, a query may receive no response in which case the port
  145. search continues by resorting to a broadcast query.  To actually
  146. transmit port search queries and responses the port search module uses
  147. the simple request-response transport protocol.
  148.  
  149.  
  150. The port search module is also responsible for authenticating a new
  151. receiver or owner for a network port if the identity of the new
  152. receiver or owner was obtained as a result of a broadcast search for
  153. the port.  This authentication is only necessary is the port is being
  154. handled securely.
  155.  
  156.  
  157.  
  158. 9.2.   Interface
  159.  
  160.  
  161.  
  162.    boolean_t  ps_init()
  163.  
  164.  
  165.  
  166. initializes  the  port  search  module.
  167.  
  168.  
  169.  
  170.    ps_do_port_search(port_rec_ptr,new_information,new_nport_ptr,retry)
  171.    port_rec_ptr_t                port_rec_ptr;
  172.    boolean_t                         new_information;
  173.    network_port_ptr_t          new_nport_ptr;
  174.    int                                   (*retry)();
  175.  
  176.  
  177.  
  178. is called to begin a port search for the network port recorded in
  179. port_rec_ptr.  If the caller has new_information about the port
  180. (either the possible identity of a new receiver or owner for the port)
  181. then that new information is contained in the network port pointed to
  182. by new_nport_ptr.  retry is a function supplied by the client to be
  183. called if the port search concludes successfully.  It takes as its
  184. only parameter the port_rec_ptr.
  185.  
  186.  
  187.  
  188.    int  ps_handle_request(request,from,broadcast,crypt_level)
  189.  
  190.  
  191.  
  192. is called by disp_indata_simple to handle an incoming port search
  193. query.
  194.  
  195.  
  196.  
  197.    int  ps_handle_reply(client_id,reply,from,broadcast,crypt_level)
  198.  
  199.  
  200.  
  201. is called by disp_rr_simple to handle an incoming reply to a port
  202. search query.
  203.  
  204.  
  205.  
  206.    int  ps_handle_auth_request(request,from,broadcast,crypt_level)
  207.  
  208.  
  209.  
  210. is called by disp_indata_simple to handle an incoming request for
  211. authentication of a receiver or owner.
  212.  
  213.  
  214.  
  215.    int ps_handle_auth_reply(client_id,reply,from,broadcast,crypt_level)
  216.  
  217.  
  218.  
  219. is called by disp_indata_simple to handle an incoming reply to a
  220. request for authentication of a receiver or owner.
  221.  
  222.  
  223.  
  224.                   26
  225.  
  226.  
  227. 10.   Key Management
  228.  
  229.  
  230.  
  231. 10.1.   Description
  232.  
  233.  
  234.  
  235. The key management module maintains a table which maps remote hosts to
  236. keys.  When it has to send a message securely over the network, the
  237. IPC module checks that the key management module has a key for the
  238. message's destination.  The actual encryption is done at the transport
  239. level when the message data has been placed in packets.
  240.  
  241.  
  242. If the key management module has no key for a particular remote host,
  243. or the key that it possesses is obsolete, then it must call upon the
  244. local KDS (Key Distribution Server) to do a key exchange.  The local
  245. KDS uses a central KDS to perform the key exchange.  After the key
  246. exchange is complete, the key management module should retry the
  247. suspended IPC message.
  248.  
  249.  
  250.  
  251. 10.2.   Interface
  252.  
  253.  
  254.  
  255.    boolean_t  km_init()
  256.  
  257.  
  258.  
  259. initializes the key management module.
  260.  
  261.  
  262.  
  263.    typedef  struct  {...}  key_t,  *key_ptr_t;
  264.  
  265.  
  266.  
  267. is used to hold an encryption or decryption key.
  268.  
  269.  
  270.  
  271.    boolean_t  km_get_key(host_id,  key_ptr)
  272.    netaddr_t                         host_id;
  273.    key_ptr_t                         key_ptr;
  274.  
  275.  
  276.  
  277. looks up the key for the host_id.  If there is a key it returns TRUE
  278. and places the key in key_ptr.
  279.  
  280.  
  281.  
  282.    boolean_t  km_get_ikey(host_id,  ikey_ptr)
  283.    netaddr_t                         host_id;
  284.    key_ptr_t                         key_iptr;
  285.  
  286.  
  287.  
  288. looks up the inverse key for the host_id.  If there is a key returns
  289. TRUE and places the key in ikey_ptr.
  290.  
  291.  
  292.  
  293.    km_do_key_exchange(client_id,  client_retry,  host_id)
  294.    int                                   client_id;
  295.    int                                   (*client_retry)();
  296.    netaddr_t                         host_id;
  297.  
  298.  
  299.  
  300. is called by a client module to get a key exchange done for host_id.
  301. When the key exchange succeeds, the key management module calls the
  302. function client_retry with the parameter client_id to inform the
  303. client that there is now a key for the host.
  304.  
  305.  
  306.  
  307.                   27
  308.  
  309.  
  310. km_kds_connect(server_port, kds_port)
  311. port_t                              server_port;
  312. port_t                              kds_port;
  313.  
  314.  
  315.  
  316. is called by the local KDS to register its port (kds_port) with the
  317. network server.
  318.  
  319.  
  320.  
  321.    km_use_key_for_host(server_port,  host_id,  key)
  322.    port_t                              server_port;
  323.    netaddr_t                         host_id;
  324.    key_t                               key;
  325.  
  326.  
  327.  
  328. is called by the local KDS to tell the network server to use key for
  329. all future communication with host_id.
  330.  
  331.  
  332. In the above two calls the server_port should always be a special port
  333. which is known only to the network server and the local KDS.  The
  334. network server is responsible for starting the KDS and passing send
  335. rights to this special port to the KDS.
  336.  
  337.  
  338.  
  339. 11.   Crypt
  340.  
  341.  
  342.  
  343. The crypt module is responsible for the actual encryption and
  344. decryption of packets that are to be sent out over the network and
  345. received over the network.
  346.  
  347.  
  348.  
  349. 11.1.   Interface
  350.  
  351.  
  352.  
  353.    typedef  struct  {...}  netipc_t,  *netipc_ptr_t;
  354.  
  355.  
  356.  
  357. points to an Internet packet encapsulated in a MACH IPC message.
  358.  
  359.  
  360.  
  361.    int  crypt_encrypt_packet(packet_ptr,  crypt_level)
  362.    netipc_ptr_t                    packet_ptr;
  363.    int                                   crypt_level;
  364.  
  365.  
  366.  
  367. encrypts the packet pointed to by packet_ptr at the encryption level
  368. given by crypt_level.  Returns either CRYPT_SUCCESS or CRYPT_FAILURE
  369. if there is no key for the remote host.
  370.  
  371.  
  372.  
  373.    crypt_decrypt_packet(packet_ptr, crypt_level)
  374.    netipc_ptr_t                    packet_ptr;
  375.    int                                   crypt_level;
  376.  
  377.  
  378.  
  379. decrypts the packet pointed to by packet_ptr at the encryption level
  380. given by crypt_level.  Returns either CRYPT_SUCCESS, CRYPT_FAILURE if
  381. there is no key for the remote host or CRYPT_CHECKSUM_FAILURE if the
  382. decrypted checksum is incorrect.
  383.  
  384.  
  385.  
  386.                   28
  387.  
  388.  
  389. 12.   Network Name Service
  390.  
  391.  
  392.  
  393. 12.1.   Description
  394.  
  395.  
  396.  
  397. The network name service module provides a simple name service that is
  398. sufficient to boot-strap a higher-level name service that will provide
  399. a distributed and replicated user-level name service.  The network
  400. name service is host-directed; that is requests for name look ups are
  401. sent to specific hosts and are not broadcast.
  402.  
  403.  
  404.  
  405. 12.2.   Interface
  406.  
  407.  
  408.  
  409.    boolean_t  netname_init()
  410.  
  411.  
  412.  
  413. initializes the network name module.
  414.  
  415.  
  416.  
  417.    nn_remove_entries(port_id)
  418.    port_t                              port_id;
  419.  
  420.  
  421.  
  422. removes all entries for the local port port_id from the local name
  423. table.
  424.  
  425.  
  426.  
  427.    typedef  char  netname_name_t[80]
  428.  
  429.  
  430.  
  431.    kern_return_t  netname_check_in(ServPort,port_name,signature,port_id)
  432.    vport_t                            ServPort;
  433.    netname_name_t                port_name;
  434.    port_t                              signature;
  435.    port_t                              port_id;
  436.  
  437.  
  438.  
  439. checks in the port port_id under the name port_name protected by
  440. signature.
  441.  
  442.  
  443.  
  444.    kern_return_t  netname_look_up(ServPort,host_name,port_name,port_id)
  445.    port_t                              ServPort;
  446.    netname_name_t                host_name;
  447.    netname_name_t                port_name;
  448.    port_t                              *port_id;
  449.  
  450.  
  451.  
  452. looks up port_name at host given by host_name.  Returns in port_id the
  453. port found.
  454.  
  455.  
  456.  
  457.    kern_return_t  netname_check_out(ServPort,port_name,signature,port_id)
  458.    port_t                              ServPort;
  459.    netname_name_t                port_name;
  460.    port_t                              signature;
  461.  
  462.  
  463.  
  464. checks out the port checked in under port_name.  The signature must
  465. match the signature supplied to the netname_check_in call.
  466.  
  467.  
  468.  
  469.                   29
  470.  
  471.  
  472.    kern_return_t  netname_version(ServPort,version)
  473.    port_t                              ServPort;
  474.    netname_name_t                version;
  475.  
  476.  
  477.  
  478. returns in version some version identification for the network server.
  479.  
  480.  
  481.  
  482.    int  nn_handle_request(request,from,broadcast,crypt_level)
  483.  
  484.  
  485.  
  486. is called by disp_indata_simple to handle an incoming request for a
  487. network name look up.
  488.  
  489.  
  490.  
  491.    int  nn_handle_reply(client_id,reply,from,broadcast,crypt_level)
  492.  
  493.  
  494.  
  495. is called by disp_rr_simple to handle an incoming response to a
  496. request for a network name look up.
  497.  
  498.  
  499.  
  500. 13.   Memory Management
  501.  
  502.  
  503.  
  504. 13.1.   Operation
  505.  
  506.  
  507.  
  508. The memory management module is responsible for allocating and
  509. deallocating various objects used by the different modules, such as
  510. port and message records, buffers, and so on.  It attempts to use
  511. knowledge of the types of objects required to achieve good
  512. performance.  It tries to reduce the load placed on the MACH virtual
  513. memory system.
  514.  
  515.  
  516.  
  517. 13.2.   Interface
  518.  
  519.  
  520.  
  521.    boolean_t  mem_init()
  522.  
  523.  
  524.  
  525. initializes the memory management module.
  526.  
  527.  
  528.  
  529.   int  mem_clean()
  530.  
  531.  
  532.  
  533. attempts to free as much unused space as possible to reduce the paging
  534. load on the operating system; it is potentially slow.
  535.  
  536.  
  537.  
  538.    pointer_t  mem_allocobj(objtype)
  539.    int                                   objtype;
  540.  
  541.  
  542.  
  543. allocates one instance of an object of the given objtype and returns
  544. its address, or 0 in case of failure.
  545.  
  546.  
  547.  
  548.    void  mem_deallocobj(ptr,objtype)
  549.    pointer_t                         ptr;
  550.    int                                   objtype;
  551.  
  552.  
  553.                   30
  554.  
  555.  
  556. deallocates an object of objtype previously allocated using
  557. mem_allocobj.
  558.  
  559.  
  560.  
  561.    pointer_t  mem_alloc(size,aligned)
  562.    int                                   size;
  563.    boolean_t                         aligned;
  564.  
  565.  
  566.  
  567. allocates a memory area of arbitrary size; it returns 0 in case of
  568. failure.
  569.  
  570.  
  571.  
  572.    void  mem_dealloc(ptr,size)
  573.    pointer_t                         ptr;
  574.    int                                   size;
  575.  
  576.  
  577.  
  578. deallocates memory previously allocated by mem_dealloc.
  579.  
  580.  
  581.  
  582. 14.   Read/Write Locks
  583.  
  584.  
  585.  
  586. The read/write locks module provides locks which can have multiple
  587. readers and signals threads waiting for a lock when it becomes free.
  588.  
  589.  
  590.  
  591. 14.1.   Interface
  592.  
  593.  
  594.  
  595.    typedef  enum  {PERM_READ,  PERM_READWRITE}  rw_perm_t;
  596.    typedef  enum  {NOBLOCK  =  0,  BLOCK  =  1}  rw_block_t;
  597.    typedef  struct  lock  {...}  *lock_t;
  598.  
  599.  
  600.    lock_t  lk_alloc()
  601.  
  602.  
  603.  
  604. allocates a read/write lock.
  605.  
  606.  
  607.  
  608.    void  lk_free(lock)
  609.  
  610.  
  611.  
  612.    frees a read/write lock.
  613.  
  614.  
  615.  
  616.    int  lk_lock(lock,  perm,  block)
  617.    lock_t                              lock;
  618.    rw_perm_t                         perm;
  619.    rw_block_t                       block;
  620.  
  621.  
  622.  
  623. locks the lock for type perm.  If block is true, then this calls
  624. blocks waiting until the lock can be obtained, otherwise the function
  625. returns 0 if the lock cannot be obtained.
  626.  
  627.  
  628.  
  629.    void  lk_unlock(lock)
  630.    lock_t                              lock;
  631.  
  632.  
  633.  
  634. unlocks the lock.
  635.  
  636.  
  637.                   31
  638.  
  639.  
  640. 15.   Locked Queue Module
  641.  
  642.  
  643.  
  644. The locked queue module provides functions to manipulate items on
  645. queues.  When a queue is accessed it is always locked before being
  646. manipulated.
  647.  
  648.  
  649.  
  650. 15.1.   Interface
  651.  
  652.  
  653.  
  654.    typedef  struct  {...}  *lock_queue_t;
  655.    typedef  struct  queue_item  {struct  queue_item  *next}  *queue_item_t;
  656.  
  657.  
  658.  
  659.    lock_queue_t  lq_alloc()
  660.  
  661.  
  662.  
  663. allocates and initializes a new locked queue.
  664.  
  665.  
  666.  
  667.    void  lq_init_queue(queue)
  668.    lock_queue_t                    queue;
  669.  
  670.  
  671.  
  672. re-initializes the already allocated queue.
  673.  
  674.  
  675.  
  676.    void  lq_prequeue(queue,  item)
  677.    lock_queue_t                    queue;
  678.    queue_item_t                    item;
  679.  
  680.  
  681.  
  682. inserts item at the head of queue.
  683.  
  684.  
  685.  
  686.    void  lq_insert_in_queue(queue,  test,  item,  args)
  687.    lock_queue_t                    queue;
  688.    int                                   (*test)();
  689.    queue_item_t                    item;
  690.    int                                   arg;
  691.  
  692.  
  693.  
  694. inserts item in the ``correct'' position on queue.  The correct
  695. position is determined by calling the user-supplied function test on
  696. item, arg and the members of queue until it returns TRUE.
  697.  
  698.  
  699.  
  700.    boolean_t  lq_remove_from_queue(queue,  item)
  701.    lock_queue_t                    queue;
  702.    queue_item_t                    item;
  703.  
  704.  
  705.  
  706. removes item from queue if item is present on the queue.  Returns TRUE
  707. is item was deleted from queue, FALSE otherwise.
  708.  
  709.  
  710.  
  711.    boolean_t  lq_cond_delete_from_queue(queue,  test,  item)
  712.    lock_queue_t                    queue;
  713.    int                                   (*test)();
  714.    queue_item_t                    item;
  715.    int                                   arg;
  716.  
  717.  
  718.                   32
  719.  
  720.  
  721. performs the user-supplied function test on item, arg and on
  722. successive elements of queue.  If it returns TRUE, then the current
  723. element of the queue is deleted.
  724.  
  725.  
  726.  
  727.    boolean_t  lq_on_queue(queue,  item)
  728.    lock_queue_t                    queue;
  729.    queue_item_t                    item;
  730.  
  731.  
  732.  
  733. checks to see if the item is on queue.
  734.  
  735.  
  736.  
  737.    queue_item_t  lq_dequeue(queue)
  738.    lock_queue_t                    queue;
  739.  
  740.  
  741.  
  742. if queue is not empty remove and return the queue item which is at the
  743. head of it.
  744.  
  745.  
  746.  
  747.    queue_item_t  lq_blocking_dequeue(queue)
  748.    lock_queue_t                    queue;
  749.  
  750.  
  751.  
  752. if queue is empty, a wait is done until it is non-empty.  Removes and
  753. returns the queue item which is at the head of queue.
  754.  
  755.  
  756.  
  757.    void  lq_enqueue(queue,  item);
  758.    lock_queue_t                    queue;
  759.    queue_item_t                    item;
  760.  
  761.  
  762.  
  763. inserts item at the tail of queue.
  764.  
  765.  
  766.  
  767.    queue_item_t  lq_find_in_queue(queue,  fn,  args)
  768.    lock_queue_t                    queue;
  769.    int                                   (*fn)();
  770.    int                                   arg;
  771.  
  772.  
  773.  
  774. returns a queue_item_t which is found by applying the user-supplied
  775. function fn to successive elements of queue and arg until fn returns
  776. TRUE.
  777.  
  778.  
  779.  
  780.    void  lq_map_queue(queue,  fn,  args);
  781.    lock_queue_t                    queue;
  782.    int                                   (*fn)();
  783.     int                                   arg;
  784.  
  785.  
  786.  
  787. applies the user-supplied function fn to each successive item of queue
  788. and arg.
  789.  
  790.  
  791. In addition to the above routines, a number of equivalent routines are
  792. provided that do not acquire or release the queue lock when invoked,
  793. to be used in situations where global lock management is needed to
  794. avoid deadlock.  Those routines are prefixed with lqn_ instead of lq_.
  795.  
  796.  
  797. Finally, the network server also uses doubly-linked lists for some
  798. queues.  using the same macros used in the Mach kernel for that
  799. purpose.
  800.  
  801.  
  802.                   33
  803.  
  804.  
  805. 16.   Timer Module
  806.  
  807.  
  808.  
  809. The timer module accepts requests from other modules for events to be
  810. scheduled at some time in the future.  When the event's deadline
  811. expires the timer module calls the user-supplied function associated
  812. with the timer.
  813.  
  814.  
  815.  
  816. 16.1.   Interface
  817.  
  818.  
  819.  
  820.    boolean_t  timer_init()
  821.  
  822.  
  823.  
  824. initializes the timer module.
  825.  
  826.  
  827.  
  828.    struct  timer  {...}  *timer_t;
  829.  
  830.  
  831.    timer_t timer_alloc()
  832.  
  833.  
  834.  
  835. returns a new timer.
  836.  
  837.  
  838.  
  839.    void  timer_start(timer)
  840.    timer_t                            timer;
  841.  
  842.  
  843.  
  844. starts up timer.
  845.  
  846.  
  847.  
  848.    void  timer_stop(timer)
  849.    timer_t                            timer;
  850.  
  851.  
  852.  
  853. stops timer.
  854.  
  855.  
  856.  
  857. 17.   Miscellaneous
  858.  
  859.  
  860.  
  861. 17.1.   Unique Identifer Generator
  862.  
  863.  
  864.  
  865. Simply generates locally unique identifiers (UIDs).  The identifiers
  866. generated are unique with high probability.
  867.  
  868.  
  869.  
  870. 17.1.1.   Interface
  871.  
  872.  
  873.  
  874.    void  uid_init()
  875.  
  876.  
  877.  
  878. initializes the UID module.
  879.  
  880.  
  881.  
  882.    long  uid_get_new_uid()
  883.  
  884.  
  885.  
  886. returns a new UID.
  887.  
  888.  
  889.                   34
  890.  
  891.  
  892. 17.2.   Sbuf
  893.  
  894.  
  895.  
  896. The sbuf module provides macros that manipulate sbufs.
  897.  
  898.  
  899.  
  900. 17.2.1.   Interface
  901.  
  902.  
  903.  
  904.    void  sbuf_printf(where,  sb_ptr)
  905.    FILE                                 *where;
  906.    sbuf_ptr_t                       sb_ptr;
  907.  
  908.  
  909.  
  910. is the only exported function of the sbuf module.  It prints out the
  911. contents of the sbuf pointed to by sb_ptr.
  912.  
  913.  
  914.  
  915. 17.3.   Network Interfaces
  916.  
  917.  
  918.  
  919. Under Mach the interface to the network is an IPC interface with a
  920. filter inside the kernel determining which network packets are to be
  921. received by the network server.  Currently, many transport modules
  922. still use BSD Unix sockets to access network protocol implementations
  923. in the kernel.
  924.  
  925.  
  926.  
  927. 17.3.1.   Interface
  928.  
  929.  
  930.  
  931.    int  netipc_receive(pkt_ptr)
  932.    netipc_ptr_t                    pkt_ptr;
  933.  
  934.  
  935.  
  936. waits to receive a packet from the kernel.  Checks the packet's UDP
  937. checksum before returning to the caller.
  938.  
  939.  
  940.  
  941.    int  netipc_send(pkt_ptr)
  942.    netipc_ptr_t                    pkt_ptr;
  943.  
  944.  
  945.  
  946. calculates the UDP checksum for the packet and then sends it to the
  947. kernel for transmission over the network.
  948.  
  949.  
  950.  
  951. 17.4.   IPC Message Receive
  952.  
  953.  
  954.  
  955. 17.5.   Interface
  956.  
  957.  
  958.  
  959.    int  netmsg_receive(msg_ptr)
  960.    msg_header_t                    *msg_ptr;
  961.  
  962.  
  963.  
  964. does a non-blocking receive for a local IPC message.
  965.  
  966.  
  967.  
  968.                   35
  969.  
  970.  
  971. 17.6.   Debugging
  972.  
  973.  
  974.  
  975. The network server keeps a log in memory of various events happening
  976. during its operation.  This log, along with statistics on various
  977. operations, can be obtained via the logstat service exported by the
  978. network server.  In addition, many operating parameters, including the
  979. level of debugging information written to the log, can be set using
  980. this same service.
  981.  
  982.  
  983.  
  984. 17.6.1.   Interface
  985.  
  986.  
  987.  
  988. Macros and procedures called within the network server
  989.  
  990.  
  991.  
  992.    DEBUGn(condition,print_level,code,arg1,...,argn)
  993.  
  994.  
  995.  
  996. is a macro to be used to write a record containing the code and all
  997. the integer args into the log.  n is a number between 0 and 6,
  998. indicating how many integers must be copied into the log.  A log entry
  999. is only made if condition evaluates to TRUE.  In addition, if
  1000. print_level is greater or equal to the global debug.print_level, a
  1001. message is printed on stderr.
  1002.  
  1003.  
  1004.  
  1005.    DEBUG_STRING(cond,level,string)
  1006.    DEBUG_NPORT(cond,level,nport)
  1007.    DEBUG_NETADDR(cond,level,netaddr)
  1008.    DEBUG_KEY(cond,level,key)
  1009.    DEBUG_SBUF(cond,level,sbuf)
  1010.  
  1011.  
  1012.  
  1013. are similar to the DEBUGn macros, but are used to enter a string, a
  1014. network port identifier, a network address, an encryption key or an
  1015. sbuf into the log.
  1016.  
  1017.  
  1018. The DEBUG macros can be made to expand to nothing via a compile-time
  1019. switch to avoid overheads at execution time.  Each of those macros has
  1020. an equivalent LOG macro that can be enabled or disabled independently;
  1021. those LOG macros are intended for events that should always be entered
  1022. in the log and are infrequent enough that the overhead involved is
  1023. negligible.
  1024.  
  1025.  
  1026.  
  1027.    ERROR((msg,format,args...))
  1028.  
  1029.  
  1030.  
  1031. is used to print out a message on stderr an make an entry in the log.
  1032. The argument should be a valid set of arguments for sprintf, with the
  1033. message string msg.
  1034.  
  1035.  
  1036.  
  1037.    void  panic(error_msg)
  1038.    char                                 *error_msg;
  1039.  
  1040.  
  1041.  
  1042. is called if something catastrophic happens.  Prints out the
  1043. error_msg, dumps the log and terminates the network server.
  1044.  
  1045.  
  1046.  
  1047.    void  ipaddr_to_string(output_string,  input_address)
  1048.    char                                 *output_string;
  1049.    netaddr_t                         input_address;
  1050.  
  1051.  
  1052.  
  1053.                   36
  1054.  
  1055.  
  1056. Translates the input_address IP address into a printable
  1057. representation in output_string.
  1058.  
  1059.  
  1060.  
  1061. Procedures exported outside the network server: The following
  1062. procedures can be called remotely by sending requests on a port
  1063. checked-in as NM_LOGSTAT in the network server.
  1064.  
  1065.  
  1066.  
  1067.    kern_return_t  ls_sendlog(ServPort,old_log_ptr,old_log_size,
  1068.                                            cur_log_ptr,cur_log_size)
  1069.    port_t                ServPort;
  1070.    log_ptr_t           *old_log_ptr;
  1071.    unsigned  int      *old_log_size;
  1072.    log_ptr_t           *cur_log_ptr;
  1073.    unsigned  int      *cur_log_size;
  1074.  
  1075.  
  1076.  
  1077. is used to obtain both network server logs in the response message.
  1078. The old and new logs correspond to the two alternating logs used to
  1079. record events.
  1080.  
  1081.  
  1082.  
  1083.    kern_return_t  ls_resetlog(ServPort)
  1084.    port_t                ServPort;
  1085.  
  1086.  
  1087.  
  1088. resets the log to zero size.
  1089.  
  1090.  
  1091.  
  1092.    kern_return_t  ls_writelog(ServPort)
  1093.    port_t                ServPort;
  1094.  
  1095.  
  1096.  
  1097. causes the network server to write its log in a file NMLOG in its
  1098. current working directory.
  1099.  
  1100.  
  1101.  
  1102.    kern_return_t  ls_sendstat(ServPort,stat_ptr,stat_size)
  1103.    port_t                ServPort;
  1104.    stat_ptr_t          *stat_ptr;
  1105.    unsigned  int      *stat_size;
  1106.  
  1107.  
  1108.  
  1109. is used to obtain a record with the vital network server statistics in
  1110. the response.
  1111.  
  1112.  
  1113.  
  1114.    kern_return_t  ls_resetstat(ServPort)
  1115.    port_t                ServPort;
  1116.  
  1117.  
  1118.  
  1119. resets all statistics counters to zero.
  1120.  
  1121.  
  1122.  
  1123.    kern_return_t  ls_senddebug(ServPort,debug_ptr,debug_size)
  1124.    port_t                ServPort;
  1125.    debug_ptr_t        *debug_ptr;
  1126.    unsigned  int      *debug_size;
  1127.  
  1128.  
  1129.  
  1130. is used to obtain a record with all the debugging flags used to
  1131. control the operation of the DEBUG macros.
  1132.  
  1133.  
  1134.                   37\
  1135.  
  1136.  
  1137.    kern_return_t  ls_setdebug(ServPort,debug_ptr,debug_size)
  1138.    port_t                ServPort;
  1139.    debug_ptr_t        *debug_ptr;
  1140.    unsigned  int      *debug_size;
  1141.  
  1142.  
  1143.  
  1144. is used to replace the record with all the debugging flags used to
  1145. control the operation of the DEBUG macros.
  1146.  
  1147.  
  1148.  
  1149.    kern_return_t  ls_sendparam(ServPort,param_ptr,param_size)
  1150.    port_t                ServPort;
  1151.    param_ptr_t        *param_ptr;
  1152.    unsigned  int      *param_size;
  1153.  
  1154.  
  1155.  
  1156. is used to obtain a record with the network server control parameters.
  1157.  
  1158.  
  1159.  
  1160.    kern_return_t  ls_setparam(ServPort,param_ptr,param_size)
  1161.    port_t                ServPort;
  1162.    param_ptr_t        *param_ptr;
  1163.    unsigned  int      *param_size;
  1164.  
  1165.  
  1166.  
  1167. is used to replace the record with the network server control
  1168. parameters.
  1169.  
  1170.  
  1171.  
  1172.    kern_return_t  ls_sendportstat(ServPort,port_stat_ptr,port_stat_size)
  1173.    port_t                ServPort;
  1174.    port_stat_ptr_t  *port_stat_ptr;
  1175.    unsigned  int      *port_stat_size;
  1176.  
  1177.  
  1178.  
  1179. is used to obtain a record with the port record statistics.
  1180.  
  1181.  
  1182.  
  1183. 17.7.   Camelot Support
  1184.  
  1185.  
  1186.  
  1187. The Camelot Distributed Transaction Facility [3 ] requires special
  1188. handling for IPC messages used in Camelot transactions.  This handling
  1189. is performed in a special Camelot module, not described, here, that
  1190. behaves as an extra step in the translation process for incoming and
  1191. outgoing IPC messages.
  1192.  
  1193.  
  1194. In addition, Camelot also requires some specialized name servers, also
  1195. implemented in the Camelot module.
  1196.  
  1197.  
  1198.  
  1199. 17.8.   Kernel Netport Support
  1200.  
  1201.  
  1202.  
  1203. Certain Mach kernels provide an experimental feature, called Netport
  1204. or MACH_NP with which Kernel port records may be flagged as
  1205. corresponding to local representatives for remote network ports.
  1206. Under certain very restricted conditions, the kernel may, upon
  1207. processing a message destined for one of these ports, send the message
  1208. directly to the remote node instead of handing it to the network
  1209. server.  This scheme results in improved performance by avoiding the
  1210. overhead of invoking the network servers on both ends of the
  1211. communication.  Correctness is assured by having the kernel abort its
  1212. transmission and
  1213.  
  1214.  
  1215.                   38
  1216.  
  1217.  
  1218. reflect the message back to the network server as soon as a situation
  1219. arises that is too complex for the Netport code to handle.
  1220.  
  1221.  
  1222. When enabled, all modules in the network server that modify network
  1223. port records enter the correct information in the kernel port records
  1224. to allow the Netport code to function.
  1225.  
  1226.  
  1227.  
  1228. 17.9.   Initialization
  1229.  
  1230.  
  1231.  
  1232. The network server initialization sequence takes care of detecting
  1233. modules that require kernel support not present on the current node,
  1234. and of setting the working parameters accordingly.  These include:
  1235.  
  1236.  
  1237.  
  1238.     o Access to a network interface.  If there is no network, the
  1239.       network server degenerates into a simple local Name Server, as
  1240.       specified by the conf_network parameter.
  1241.  
  1242.     o Netport support: controlled by the conf_netport parameter.
  1243.  
  1244.     o VMTP support.  The transport_default parameter is set to the
  1245.       index of the best transport protocol available.
  1246.  
  1247.  
  1248.  
  1249. 17.9.1.   Interface
  1250.  
  1251.  
  1252.  
  1253.    boolean_t  nm_init()
  1254.  
  1255.  
  1256.  
  1257. initializes the network server by calling and checking the error
  1258. returns for all the module initialization functions.
  1259.  
  1260.  
  1261.  
  1262.  
  1263. Appendix
  1264.  
  1265.  
  1266.  
  1267. A   Compiling a Network Server
  1268.  
  1269.  
  1270.  
  1271. The various configuration options for the Network Server are all
  1272. defined in the file config.h, which should simply be edited before
  1273. compiling the system.  The option settings in the file as distributed
  1274. are suitable for a normal generic configuration.
  1275.  
  1276.  
  1277. The configuration options are:
  1278.  
  1279.  
  1280.  
  1281. NET_LOG enable the LOGn macros.
  1282.  
  1283. NET_DEBUG enable the DEBUGn macros.
  1284.  
  1285. NET_TRACE enable tracing of procedure calls, under control of a
  1286.     command line switch.
  1287.  
  1288. NET_PRINT enable printing from the LOG and DEBUG macros.
  1289.  
  1290. LOCK_THREADS do not allow more than one thread to run at any one time.
  1291.     To use only for debugging.
  1292.  
  1293. NM_STATISTICS enable normal statistics gathering.
  1294.  
  1295. NETPORT enable entering information in the kernel port records for use
  1296.     by the Netport option.
  1297.  
  1298. PORTSTAT enable port statistics gathering.
  1299.  
  1300.  
  1301.                   39
  1302.  
  1303.  
  1304. RPCMOD     enable the RPC optimization, and the request-response
  1305.     transport
  1306.     interface.  Should always be on.
  1307.  
  1308. COMPAT     enable special operating mode for compatibility with the
  1309.     previous implementation (Mach 1.0 and 2.0) of the Network Server.
  1310.  
  1311. NOTIFY    explicitly allocate a notify port, which is not created by
  1312.     default in newer versions of the Mach kernel.
  1313.  
  1314. CAMELOT    include the Camelot module in the network server.
  1315.  
  1316. NM_USE_KDS use an external Key Distribution Server.
  1317.  
  1318. USE_VMTP include the VMTP transport module in the network server.
  1319.  
  1320. USE_DELTAT include the Delta-t transport module in the network server.
  1321.  
  1322. USE_CRYPT include the Crypt module in the network server.
  1323.  
  1324. USE_DES include the DES encryption module in the network server.
  1325.  
  1326. USE_MULTPERM include the ``multiple permutations'' encryption module
  1327.     in the network server.
  1328.  
  1329. USE_NEWDES include the ``new'' DES encryption module in the network
  1330.     server.
  1331.  
  1332. USE_XOR include the ``exclusive or'' encryption module in the network
  1333.     server.
  1334.  
  1335. USE_KEYMAN include the keymanager module in the network server.
  1336.  
  1337. USE_TCP    include the TCP transport module in the network server.
  1338.  
  1339. USE_DATAGRAM include the DATAGRAM transport module in the network
  1340.     server.
  1341.  
  1342. USE_SRR include the SRR transport module in the network server.
  1343.  
  1344.  
  1345.  
  1346. Both USE_VMTP and NETPORT require kernel support that is not normally
  1347. present.  Normally, USE_TCP, USE_SRR and USE_DATAGRAM should always be
  1348. enabled for the system to work.
  1349.  
  1350.  
  1351. In addition to the configuration options, the file config.h also
  1352. contains all the definitions needed to compile the network server on
  1353. various architectures.  It is the only file that should be modified
  1354. when porting the network server to a new architecture.
  1355.  
  1356.  
  1357.  
  1358. References
  1359.  
  1360.  
  1361. [1] Cheriton, D.  VMTP: A Transport Protocol for the Next Generation of
  1362.     Communication Systems.  In: Proceedings of the ACM SIGCOMM 86
  1363.     Symposium on Communications Architectures and Protocols.  ACM, 1986,
  1364.     pp. 406-415.
  1365.       
  1366. [2] Sansom, R. D., Julin, D. P., and Rashid, R. F. Extending a
  1367.     Capability Based System into a Network Environment.  In: SIGCOMM
  1368.     '86 Symposium: Communications Architectures & Protocols, ACM
  1369.     SIGCOMM.  1986.  Also available as Technical Report CMU-CS-86-115.
  1370.  
  1371. [3] Spector, A. Z., Bloch, J. J., Daniels, D. S., Draves, R. P.,
  1372.     Duchamp, D., Eppinger, J. L., Menees, S. G., and Thompson, D. S.
  1373.     The Camelot Project.  Database Engineering, vol. 9 (1986).  Also
  1374.     available as Technical Report CMU-CS-86-166, Carnegie-Mellon
  1375.     University, November 1986.
  1376.  
  1377.