From c055fb17a38563297be3ff55a5dcb2e0e582a7e8 Mon Sep 17 00:00:00 2001 From: qorg11 Date: Tue, 20 Oct 2020 15:48:23 +0200 Subject: [PATCH] Improved documentation --- README.MD | 5 +- doc/index.md | 133 --------------------------------------------- doc/lainsafe.1 | 35 +++++++++++- doc/lainsafe.md | 72 ++++++++++++++++++++++++ doc/lainsafecli.md | 75 +++++++++++++++++++++++++ 5 files changed, 185 insertions(+), 135 deletions(-) delete mode 100644 doc/index.md create mode 100644 doc/lainsafe.md create mode 100644 doc/lainsafecli.md diff --git a/README.MD b/README.MD index 69313cb..38e4fe3 100644 --- a/README.MD +++ b/README.MD @@ -8,6 +8,9 @@ the file 2. There you go. +For more detailed information, look at the +[manpage](https://codeberg.org/qorg11/lainsafe/src/branch/master/doc/lainsafe.md) + ## lainsafecli ### Installation @@ -104,4 +107,4 @@ Thanks! [Liberapay](https://liberapay.com/qorg11) Bitcoin: bc1qghl6f27dpgktynpvkrxte2s3gm9pcv8vlwuzum -Monero: 47QTumjtqJabbo1s9pLDdXeJarLVLfs1AaEcbi1xrEiV852mqcbe5AHLNXTk7tH9MscxcxQDfJQnvH5LpxvfgwSJQZ3zbS6 \ No newline at end of file +Monero: 47QTumjtqJabbo1s9pLDdXeJarLVLfs1AaEcbi1xrEiV852mqcbe5AHLNXTk7tH9MscxcxQDfJQnvH5LpxvfgwSJQZ3zbS6 diff --git a/doc/index.md b/doc/index.md deleted file mode 100644 index b9088bb..0000000 --- a/doc/index.md +++ /dev/null @@ -1,133 +0,0 @@ -# lainsafecli documentation - -## History - -[delegao](https://kill-9.xyz/rocks/people/delegao) and I were talking about how much I hate the modern web. He runs which is the same but with JS, so I think it sucked. I started to make lainsafe to replace lolisafe. - -## Lainsafe installation - -Just put index.html and upload.cgi in a HTTP directory. I use fcgi to run my cgi scripts. So it's what i recommend. To install fcgi on Debian, run: ```# apt install fcgiwrap``` - -here's an example configuration for lainsafe, using nginx. - -~~~ -server -{ - server_name lainsafe.foo.tld; - - listen 80; - listen [::]:80; - client_max_body_size 100m; # max size 100MBs, change 10 to 100 in upload.cgi in line 30 - root /var/www/lainsafe; - - location ~ \.cgi$ { - gzip off; - include /etc/nginx/fastcgi_params; - fastcgi_pass unix:/var/run/fcgiwrap.socket; - fastcgi_index index.cgi; - fastcgi_param SCRIPT_FILENAME /var/www/lainsafe/$fastcgi_script_name; - } -} -~~~ - -## lainsafecli - -lainsafecli is a command line interface for lainsafe. It can be used -in whatever that runs Perl. Installation is simple: if you're running -Debian install the libwww-perl package. If you are not running Debian, -search for that package in your repositories. Or use ```# cpan -i -LWP::UserAgent``` Also LWP::UserAgent::https is needed. In Debian, -install liblwp-protocol-https-perl, in other distros try # cpan -i -LWP::UserAgent - -### Installation - -I haven't made a package for lainsafecli yet. So installation is basically: - -~~~ -# wget https://raw.githubusercontent.com/qorg11/lainsafe/master/lainsafecli \ --O /bin/lainsafecli && chmod +x /bin/lainsafecli -~~~ - -That will install lainsafecli, run ```lainsafecli``` to make sure it is installed. - -### Configuration - -lainsafecli is a simple software. So it has just 2 configurable -parameters. lainsafecli do not have a config file. So you have to -change these parameters in the executable file. - -These parameters are located in the line 34 of lainsafecli. - -```$DEFAULT_SERVER``` the server that will be used if --server is not -specified. -```$DISPLAY_ASCII``` By default is true, change to 0 if you don't want -the Lain ASCII art to appear when you upload a file. - -the most "official" lainsafe instance is . - -### Usage - -Before 1b8373 - -~~~ -USAGE: lainsafecli [--server] --file=FILE -~~~ - -After 1b8373 - -~~~ -USAGE: lainsafecli [--server] FILE -~~~ - - -for example: - -```lainsafe --server=https://lainsafe.foo.bar sicp.pdf``` - -will upload sicp.pdf to lainsafe.foo.bar - -### Sample output - -In this output, ```$DEFAULT_SERVER``` is lainsafe.delegao.moe. and ``` -$DISPLAY_ASCII``` equals 1 (true) - -~~~ -lainsafecli sicp.pdf - - _..-- ----- --.._ - ,-'' `-. - , \ - / \ - / ` . \ - ' / || ; - ; ^/| |/ | | - | /v /\`-'v√\'-|\ , - | /v` ,--- ---- .^.| ; - : | /´@@`, ,@@`\ | ; - ' | '. @@ / \@@ / |\ |; - | ^| ----- --- | \/|| - ` |` | /\ / - \ \ |/ |, - ' ; \ /| | - ` \ -- / | | - ` `. .-' | / - v,- `;._ _.; | | - `'`\ |-_ -^'^'| | - ------ |/ - -https://lainsafe.delegao.moe/files/nzOhDKtB.pdf -~~~ - -# upload.cgi - -```upload.cgi``` is the perl script that do all the works. You could -delete index.cgi from your sever and just upload.cgi. You'd upload -files through ```lainsafecli```. - -## Configuration - -Only one parameter: ```$MAX_SIZE``` specify, in megabytes, the max size of files allowed. So for example. If you want to set 100MBs as max size . ```$MAX_SIZE``` would be like this: ```$MAX_SIZE = 1024*1024*100``` - -If someone tries to upload a file bigger than 100MBs. It will return -Max size for a file is 100 MBs, then, upload.cgi will die. diff --git a/doc/lainsafe.1 b/doc/lainsafe.1 index 9f93562..362c105 100644 --- a/doc/lainsafe.1 +++ b/doc/lainsafe.1 @@ -10,6 +10,10 @@ lainsafe is a simple file upload server written in Perl + CGI. It runs in a Web server (i.e. nginx) with a CGI handler (i.e. fcgiwrap) +You also have to install the dependencies, in Debian: + +.B apt install nginx libcgi-pm-perl + .SH INSTALLATION You can use any web server for running lainsafe. However, nginx is @@ -37,8 +41,37 @@ server } } .EE - +.PP The document root will be /var/www/lainsafe (be sure to change it in .I root and .I fastcgi_param SCRIPT_FILENAME if you're going to use another directory + +You also have to give the .cgi files +x permissions: + +.I chmod +x *.cgi + +.And also, create the "files" directory manually, and give it +permissions so the user that is running nginx (usually) +.I www-data +can write on it. + +.SH TROUBLESHOOTING + +.B 502 Bad Gateway + +Probably you're missing the +.I CGI +dependence, so install it with CPAN or apt + +.I cpan -i CGI + +.I apt install libcgi-pm-perl + +If you still get this problem, run +.I perl .cgi +so perl can help you debug the problem. + +.B 403 is returned + +You probably forgot to give the files execution permissions. diff --git a/doc/lainsafe.md b/doc/lainsafe.md new file mode 100644 index 0000000..044627d --- /dev/null +++ b/doc/lainsafe.md @@ -0,0 +1,72 @@ +NAME +==== + +lainsafe - Simple file upload + +DESCRIPTION +=========== + +lainsafe is a simple file upload server written in Perl + CGI. + +It runs in a Web server (i.e. nginx) with a CGI handler (i.e. fcgiwrap) + +You also have to install the dependencies, in Debian: + +**apt install nginx libcgi-pm-perl** + +INSTALLATION +============ + +You can use any web server for running lainsafe. However, nginx is +recommended. The following configuration should work for nginx: + +*/etc/nginx/sites-enabled/lainsafe.conf* + + server + { + server_name lainsafe.foo.tld; + + listen 80; + listen [::]:80; + client_max_body_size 100m; # max size 100MBs, change 10 to 100 + # in upload.cgi in line 30 + root /var/www/lainsafe; + + location ~ .cgi$ { + gzip off; + include /etc/nginx/fastcgi_params; + fastcgi_pass unix:/var/run/fcgiwrap.socket; + fastcgi_index index.cgi; + fastcgi_param SCRIPT_FILENAME /var/www/lainsafe/$fastcgi_script_name; + } + } + +The document root will be /var/www/lainsafe (be sure to change it in +*root* and *fastcgi\_param SCRIPT\_FILENAME if you\'re going to use +another directory* + +You also have to give the .cgi files +x permissions: + +*chmod +x \*.cgi* + +permissions so the user that is running nginx (usually) *www-data* can +write on it. + +TROUBLESHOOTING +=============== + +**502 Bad Gateway** + +Probably you\'re missing the *CGI* dependence, so install it with CPAN +or apt + +*cpan -i CGI* + +*apt install libcgi-pm-perl* + +If you still get this problem, run *perl \.cgi* so perl can help +you debug the problem. + +**403 is returned** + +You probably forgot to give the files execution permissions. diff --git a/doc/lainsafecli.md b/doc/lainsafecli.md new file mode 100644 index 0000000..cf0d93d --- /dev/null +++ b/doc/lainsafecli.md @@ -0,0 +1,75 @@ +NAME +==== + +lainsafecli - Command line interface for lainsafe + +SYNOPSIS +======== + +lainsafecli *\[\--server=server\]* file + +DESCRIPTION +=========== + +*lainsafecli* uploads a file to a given lainsafe server. This server may +be specified with the *\--server* flag. If *\--server* is not given. The +content of the variable *\$DEFAULT\_SERVER* will be used instead. This +variable is in the script. In the official packages. this is +https://lainsafe.delegao.moe + +OPTIONS +======= + +*\--server* Sets the server to use. If it is not given \$DEFAULT\_SERVER +will be used instead. + +*\--help* Displays a simple help message and exits. This also specify +which server will be used if no *\--server* is given. + +*\--tor* Uses tor to upload the file. This requires +*LWP::Protocol::socks* to be installed on your system. You also need to +have tor running at 127.0.0.1:9050 If LWP::Protocol::socks is not +installed, \--tor is ignored, so don\'t try it + +*\--get-response* If the server returned an error, \--get-response will +make lainsafecli print the content, so it can help you find out why +lainsafecli isn\'t working! + +CONFIGURATION +============= + +there are configuration values in *lainsafecli* line 34. + +*\$DISPLAY\_ASCII* If true (Any number but 0), It will display an ASCII +art if no error returned. + +*\$STORE\_LINKS* If true, lainsafecli will store the links on a file, +specified by *\$LINKS\_FILE* + +TROUBLESHOOTING +=============== + +**whatever is not running lainsafe. But works in the browser.** + +This only happens with https lainsafe instances. To solve that. Make +sure that the module *LWP::UserAgent::https* is installed. You can +install it using *cpan(1)* + +**HTTP 413 is returned** + +The file you specified is too big for the instance. Try using another +instance. By default lainsafe supports up to 100MBs. But this can be +configured in lainsafe **AND** the web server. If the file exceds +whatever your **server** allows. lainsafe can set another limit. If the +lainsafe limit is less than the server limit. lainsafe will return its +own error message. + +AUTHORS +======= + +qorg11 \ + +LICENSE +======= + +GPLv3 or later.