| 1 | RCMD(3) BSD Programmer's Manual RCMD(3) |
| 2 | |
| 3 | N\bNA\bAM\bME\bE |
| 4 | r\brc\bcm\bmd\bd, r\brr\bre\bes\bsv\bvp\bpo\bor\brt\bt, r\bru\bus\bse\ber\bro\bok\bk - routines for returning a stream to a remote |
| 5 | command |
| 6 | |
| 7 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 8 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 9 | |
| 10 | _\bi_\bn_\bt |
| 11 | r\brc\bcm\bmd\bd(_\bc_\bh_\ba_\br _\b*_\b*_\ba_\bh_\bo_\bs_\bt, _\bi_\bn_\bt _\bi_\bn_\bp_\bo_\br_\bt, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bl_\bo_\bc_\bu_\bs_\be_\br, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\br_\be_\bm_\bu_\bs_\be_\br, |
| 12 | _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bc_\bm_\bd, _\bi_\bn_\bt _\b*_\bf_\bd_\b2_\bp); |
| 13 | |
| 14 | _\bi_\bn_\bt |
| 15 | r\brr\bre\bes\bsv\bvp\bpo\bor\brt\bt(_\bi_\bn_\bt _\b*_\bp_\bo_\br_\bt); |
| 16 | |
| 17 | _\bi_\bn_\bt |
| 18 | i\bir\bru\bus\bse\ber\bro\bok\bk(_\bu_\b__\bl_\bo_\bn_\bg _\br_\ba_\bd_\bd_\br, _\bi_\bn_\bt _\bs_\bu_\bp_\be_\br_\bu_\bs_\be_\br, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\br_\bu_\bs_\be_\br, |
| 19 | _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bl_\bu_\bs_\be_\br); |
| 20 | |
| 21 | _\bi_\bn_\bt |
| 22 | r\bru\bus\bse\ber\bro\bok\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\br_\bh_\bo_\bs_\bt, _\bi_\bn_\bt _\bs_\bu_\bp_\be_\br_\bu_\bs_\be_\br, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\br_\bu_\bs_\be_\br, |
| 23 | _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bl_\bu_\bs_\be_\br); |
| 24 | |
| 25 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26 | The r\brc\bcm\bmd\bd() function is used by the super-user to execute a command on a |
| 27 | remote machine using an authentication scheme based on reserved port num- |
| 28 | bers. The r\brr\bre\bes\bsv\bvp\bpo\bor\brt\bt() function returns a descriptor to a socket with an |
| 29 | address in the privileged port space. The r\bru\bus\bse\ber\bro\bok\bk() function is used by |
| 30 | servers to authenticate clients requesting service with r\brc\bcm\bmd\bd(). All |
| 31 | three functions are present in the same file and are used by the rshd(8) |
| 32 | server (among others). |
| 33 | |
| 34 | The r\brc\bcm\bmd\bd() function looks up the host _\b*_\ba_\bh_\bo_\bs_\bt using gethostbyname(3), re- |
| 35 | turning -1 if the host does not exist. Otherwise _\b*_\ba_\bh_\bo_\bs_\bt is set to the |
| 36 | standard name of the host and a connection is established to a server re- |
| 37 | siding at the well-known Internet port _\bi_\bn_\bp_\bo_\br_\bt. |
| 38 | |
| 39 | If the connection succeeds, a socket in the Internet domain of type |
| 40 | SOCK_STREAM is returned to the caller, and given to the remote command as |
| 41 | _\bs_\bt_\bd_\bi_\bn and _\bs_\bt_\bd_\bo_\bu_\bt. If _\bf_\bd_\b2_\bp is non-zero, then an auxiliary channel to a |
| 42 | control process will be set up, and a descriptor for it will be placed in |
| 43 | _\b*_\bf_\bd_\b2_\bp. The control process will return diagnostic output from the command |
| 44 | (unit 2) on this channel, and will also accept bytes on this channel as |
| 45 | being UNIX signal numbers, to be forwarded to the process group of the |
| 46 | command. If _\bf_\bd_\b2_\bp is 0, then the _\bs_\bt_\bd_\be_\br_\br (unit 2 of the remote command) |
| 47 | will be made the same as the _\bs_\bt_\bd_\bo_\bu_\bt and no provision is made for sending |
| 48 | arbitrary signals to the remote process, although you may be able to get |
| 49 | its attention by using out-of-band data. |
| 50 | |
| 51 | The protocol is described in detail in rshd(8). |
| 52 | |
| 53 | The r\brr\bre\bes\bsv\bvp\bpo\bor\brt\bt() function is used to obtain a socket with a privileged ad- |
| 54 | dress bound to it. This socket is suitable for use by r\brc\bcm\bmd\bd() and several |
| 55 | other functions. Privileged Internet ports are those in the range 0 to |
| 56 | 1023. Only the super-user is allowed to bind an address of this sort to |
| 57 | a socket. |
| 58 | |
| 59 | The i\bir\bru\bus\bse\ber\bro\bok\bk() and r\bru\bus\bse\ber\bro\bok\bk() functions take a remote host's IP address or |
| 60 | name, as returned by the gethostbyname(3) routines, two user names and a |
| 61 | flag indicating whether the local user's name is that of the super-user. |
| 62 | Then, if the user is _\bN_\bO_\bT the super-user, it checks the _\b/_\be_\bt_\bc_\b/_\bh_\bo_\bs_\bt_\bs_\b._\be_\bq_\bu_\bi_\bv |
| 63 | file. If that lookup is not done, or is unsuccessful, the _\b._\br_\bh_\bo_\bs_\bt_\bs in the |
| 64 | local user's home directory is checked to see if the request for service |
| 65 | is allowed. |
| 66 | |
| 67 | If this file does not exist, is not a regular file, is owned by anyone |
| 68 | other than the user or the super-user, or is writeable by anyone other |
| 69 | than the owner, the check automatically fails. Zero is returned if the |
| 70 | machine name is listed in the ``_\bh_\bo_\bs_\bt_\bs_\b._\be_\bq_\bu_\bi_\bv'' file, or the host and re- |
| 71 | mote user name are found in the ``_\b._\br_\bh_\bo_\bs_\bt_\bs'' file; otherwise i\bir\bru\bus\bse\ber\bro\bok\bk() |
| 72 | and r\bru\bus\bse\ber\bro\bok\bk() return -1. If the local domain (as obtained from |
| 73 | gethostname(2)) is the same as the remote domain, only the machine name |
| 74 | need be specified. |
| 75 | |
| 76 | The i\bir\bru\bus\bse\ber\bro\bok\bk() function is strongly preferred for security reasons. It |
| 77 | requires trusting the local DNS at most, while the r\bru\bus\bse\ber\bro\bok\bk() function re- |
| 78 | quires trusting the entire DNS, which can be spoofed. |
| 79 | |
| 80 | D\bDI\bIA\bAG\bGN\bNO\bOS\bST\bTI\bIC\bCS\bS |
| 81 | The r\brc\bcm\bmd\bd() function returns a valid socket descriptor on success. It re- |
| 82 | turns -1 on error and prints a diagnostic message on the standard error. |
| 83 | |
| 84 | The r\brr\bre\bes\bsv\bvp\bpo\bor\brt\bt() function returns a valid, bound socket descriptor on suc- |
| 85 | cess. It returns -1 on error with the global value _\be_\br_\br_\bn_\bo set according |
| 86 | to the reason for failure. The error code EAGAIN is overloaded to mean |
| 87 | ``All network ports in use.'' |
| 88 | |
| 89 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 90 | rlogin(1), rsh(1), intro(2), rexec(3), rexecd(8), rlogind(8), |
| 91 | rshd(8) |
| 92 | |
| 93 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 94 | These functions appeared in 4.2BSD. |
| 95 | |
| 96 | 4.2 Berkeley Distribution June 4, 1993 2 |