src/vfs/fish/helpers/README.fish

   1
   2                 FIles transferred over SHell protocol (V 0.0.3)
   3                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   4
   5 This protocol was designed for transferring files over a remote shell
   6 connection (rsh and compatibles). It can be as well used for transfers over
   7 rsh, and there may be other uses.
   8
   9 Client sends requests of following form:
  10
  11 #FISH_COMMAND
  12 equivalent shell commands,
  13 which may be multiline
  14
  15 Only fish commands are defined here, shell equivalents are for your
  16 information only and will probably vary from implementation to
  17 implementation. Fish commands always have priority: server is
  18 expected to execute fish command if it understands it. If it does not,
  19 however, it can try the luck and execute shell command.
  20
  21 Since version 4.7.3, the scripts that FISH sends to host machines after
  22 a command is transmitted are no longer hardwired in the Midnight
  23 Commander source code.
  24
  25 First, mc looks for system-wide set of scripts, then it checks whether
  26 current user has host-specific overrides in his per-user mc
  27 configuration directory. User-defined overrides take priority over
  28 sytem-wide scripts if they exist. The order in which the directories are
  29 traversed is as follows:
  30
  31     /usr/libexec/mc/fish
  32     ~/.local/share/mc/fish/<hostname>/
  33
  34 Server's reply is multiline, but always ends with
  35
  36 ### 000<optional text>
  37
  38 line. ### is prefix to mark this line, 000 is return code. Return
  39 codes are superset to those used in ftp.
  40
  41 There are few new exit codes defined:
  42
  43 000 don't know; if there were no previous lines, this marks COMPLETE
  44 success, if they were, it marks failure.
  45
  46 001 don't know; if there were no previous lines, this marks
  47 PRELIMinary success, if they were, it marks failure
  48
  49                                 Connecting
  50                                 ~~~~~~~~~~
  51 Client uses "echo FISH:;/bin/sh" as command executed on remote
  52 machine. This should make it possible for server to distinguish FISH
  53 connections from normal rsh/ssh.
  54
  55                                 Commands
  56                                 ~~~~~~~~
  57 #FISH
  58 echo; start_fish_server; echo '### 200'
  59
  60 This command is sent at the beginning. It marks that client wishes to
  61 talk via FISH protocol. #VER command must follow. If server
  62 understands FISH protocol, it has option to put FISH server somewhere
  63 on system path and name it start_fish_server.
  64
  65 #VER 0.0.2 <feature1> <feature2> <...>
  66 echo '### 000'
  67
  68 This command is the second one. It sends client version and extensions
  69 to the server. Server should reply with protocol version to be used,
  70 and list of extensions accepted.
  71
  72 VER 0.0.0 <feature2>
  73 ### 200
  74
  75 #PWD
  76 pwd; echo '### 200'
  77
  78 Server should reply with current directory (in form /abc/def/ghi)
  79 followed by line indicating success.
  80
  81 #LIST /directory
  82 ls -lLa $1 | grep '^[^cbt]' | ( while read p x u g s m d y n; do echo "P$p $u.$g
  83 S$s
  84 d$m $d $y
  85 :$n
  86 "; done )
  87 ls -lLa $1 | grep '^[cb]' | ( while read p x u g a i m d y n; do echo "P$p $u.$g
  88 E$a$i
  89 dD$m $d $y
  90 :$n
  91 "; done )
  92 echo '### 200'
  93
  94 This allows client to list directory or get status information about
  95 single file. Output is in following form (any line except :<filename>
  96 may be omitted):
  97
  98 P<unix permissions> <owner>.<group>
  99 S<size>
 100 d<3-letters month name> <day> <year or HH:MM>
 101 D<year> <month> <day> <hour> <minute> <second>[.1234]
 102 E<major-of-device>,<minor>
 103 :<filename>
 104 L<filename symlink points to>
 105 <blank line to separate items>
 106
 107 Unix permissions are of form X--------- where X is type of
 108 file. Currently, '-' means regular file, 'd' means directory, 'c', 'b'
 109 means character and block device, 'l' means symbolic link, 'p' means
 110 FIFO and 's' means socket.
 111
 112 'd' has three fields: month (one of strings Jan Feb Mar Apr May Jun
 113 Jul Aug Sep Oct Nov Dec), day of month, and third is either single
 114 number indicating year, or HH:MM field (assume current year in such
 115 case). As you've probably noticed, this is pretty broken; it is for
 116 compatibility with ls listing.
 117
 118 #RETR /some/name
 119 ls -l /some/name | ( read a b c d x e; echo $x ); echo '### 100'; cat /some/name; echo '### 200'
 120
 121 Server sends line with filesize on it, followed by line with ### 100
 122 indicating partial success, then it sends binary data (exactly
 123 filesize bytes) and follows them with (with no preceding newline) ###
 124 200.
 125
 126 Note that there's no way to abort running RETR command - except
 127 closing the connection.
 128
 129 #STOR <size> /file/name
 130 > /file/name; echo '### 001'; ( dd bs=4096 count=<size/4096>; dd bs=<size%4096> count=1 ) 2>/dev/null | ( cat > %s; cat > /dev/null ); echo '### 200'
 131
 132 This command is for storing /file/name, which is exactly size bytes
 133 big. You probably think I went crazy. Well, I did not: that strange
 134 cat > /dev/null has purpose to discard any extra data which was not
 135 written to disk (due to for example out of space condition).
 136
 137 [Why? Imagine uploading file with "rm -rf /" line in it.]
 138
 139 #CWD /somewhere
 140 cd /somewhere; echo '### 000'
 141
 142 It is specified here, but I'm not sure how wise idea is to use this
 143 one: it breaks stateless-ness of the protocol.
 144
 145 Following commands should be rather self-explanatory:
 146
 147 #CHMOD 1234 file
 148 chmod 1234 file; echo '### 000'
 149
 150 #DELE /some/path
 151 rm -f /some/path; echo '### 000'
 152
 153 #MKD /some/path
 154 mkdir /some/path; echo '### 000'
 155
 156 #RMD /some/path
 157 rmdir /some/path; echo '### 000'
 158
 159 #RENAME /path/a /path/b
 160 mv /path/a /path/b; echo '### 000'
 161
 162 #LINK /path/a /path/b
 163 ln /path/a /path/b; echo '### 000'
 164
 165 #SYMLINK /path/a /path/b
 166 ln -s /path/a /path/b; echo '### 000'
 167
 168 #CHOWN user /file/name
 169 chown user /file/name; echo '### 000'
 170
 171 #CHGRP group /file/name
 172 chgrp group /file/name; echo '### 000'
 173
 174 #INFO
 175 ...collect info about host into $result ...
 176 echo $result
 177 echo '### 200'
 178
 179 #READ <offset> <size> /path/and/filename
 180 cat /path/and/filename | ( dd bs=4096 count=<offset/4096> > /dev/null;
 181 dd bs=<offset%4096> count=1 > /dev/null;
 182 dd bs=4096 count=<offset/4096>;
 183 dd bs=<offset%4096> count=1; )
 184
 185 Returns ### 200 on successful exit, ### 291 on successful exit when
 186 reading ended at eof, ### 292 on successfull exit when reading did not
 187 end at eof.
 188
 189 #WRITE <offset> <size> /path/and/filename
 190
 191 Hmm, shall we define these ones if we know our client is not going to
 192 use them?
 193
 194 you can use follow parameters:
 195 FISH_FILESIZE
 196 FISH_FILENAME
 197 FISH_FILEMODE
 198 FISH_FILEOWNER
 199 FISH_FILEGROUPE
 200 FISH_FILEFROM
 201 FISH_FILETO
 202
 203 NB:
 204 'FISH_FILESIZE' used if we operate with single file name in 'unlink', 'rmdir', 'chmod', etc...
 205 'FISH_FILEFROM','FISH_FILETO'  used if we operate with two files in 'ln', 'hardlink', 'mv' etc...
 206 'FISH_FILEOWNER', 'FISH_FILEGROUPE' is a new user/group in chown
 207
 208 also flags:
 209 FISH_HAVE_HEAD
 210 FISH_HAVE_SED
 211 FISH_HAVE_AWK
 212 FISH_HAVE_PERL
 213 FISH_HAVE_LSQ
 214 FISH_HAVE_DATE_MDYT
 215
 216 That's all, folks!
 217                                                 pavel@ucw.cz