diff --git a/README b/README.md similarity index 65% rename from README rename to README.md index 663ed397..a1ba0265 100644 --- a/README +++ b/README.md @@ -1,6 +1,7 @@ # Uhub Uhub is a high performance peer-to-peer hub for the ADC network. Its low memory footprint allows it to handle several thousand users on high-end servers, or a small private hub on embedded hardware. + Uhub uses the ADC protocol, and is compatible with DC++, jUCy and other ADC clients. ## Key features @@ -14,7 +15,9 @@ Uhub uses the ADC protocol, and is compatible with DC++, jUCy and other ADC clie ## Download You can also use git to use the last up-to-date version: - $ git clone https://github.com/janvidar/uhub.git +``` +git clone https://github.com/janvidar/uhub.git +``` You can also find zip / tar.gz files of different uhub versions on https://github.com/janvidar/uhub/releases @@ -26,15 +29,15 @@ Tehnick has provided an up to date uhub PPA for Debian and Ubuntu based distribu ### Compile -See doc/compile.txt document or https://github.com/janvidar/uhub/blob/master/doc/compile.txt. +See [doc/compile.md](doc/compile.md) document or https://github.com/janvidar/uhub/blob/master/doc/compile.md ### Getting started -See doc/getstarted.txt document or https://github.com/janvidar/uhub/blob/master/doc/getstarted.txt. +See [doc/getstarted.md](doc/getstarted.md) document or https://github.com/janvidar/uhub/blob/master/doc/getstarted.md -### Use SSL +### Use TLS/SSL -See doc/ssl-documentation.txt document or https://github.com/janvidar/uhub/blob/master/doc/ssl-documentation.txt. +See [doc/tls-documentation.md](doc/tls-documentation.md) document or https://github.com/janvidar/uhub/blob/master/doc/tls-documentation.md ## Compatible clients @@ -44,4 +47,5 @@ https://en.wikipedia.org/wiki/Comparison_of_ADC_software#Client_software ## License Uhub is free and open source software, licensed under the GNU General Public License 3. -See COPYING file, https://github.com/janvidar/uhub/blob/master/COPYING or directly https://www.gnu.org/licenses/gpl-3.0.txt + +See [COPYING](COPYING) file, https://github.com/janvidar/uhub/blob/master/COPYING or directly https://www.gnu.org/licenses/gpl-3.0.txt diff --git a/admin/make_pkg_deb.sh b/admin/make_pkg_deb.sh index 096a9436..9a86aec2 100755 --- a/admin/make_pkg_deb.sh +++ b/admin/make_pkg_deb.sh @@ -30,10 +30,11 @@ cp ${PACKAGE}/doc/users.conf deb/etc/uhub echo "Welcome to uHub" > deb/etc/uhub/motd.txt # Copy other files -cp ${PACKAGE}/README deb/usr/share/doc/uhub +cp ${PACKAGE}/README.md deb/usr/share/doc/uhub cp ${PACKAGE}/AUTHORS deb/usr/share/doc/uhub gzip -c --best < ${PACKAGE}/ChangeLog > deb/usr/share/doc/uhub/changelog.gz gzip -c --best < ${PACKAGE}/doc/uhub.1 > deb/usr/share/man/man1/uhub.1.gz +gzip -c --best < ${PACKAGE}/doc/uhub-passwd.1 > deb/usr/share/man/man1/uhub-passwd.1.gz cat > deb/usr/share/doc/uhub/copyright < 3.0 or clang (or MinGW on Windows) + * Perl 5 + * openssl >= 1.1 (or use `make USE_SSL=NO`) + * sqlite > 3.x + +For Ubuntu / Debian: +``` +sudo apt-get install cmake make gcc git libsqlite3-dev libssl-dev +``` + +## Linux, Mac OSX, FreeBSD, NetBSD and OpenBSD +``` +cmake . +make +sudo make install +``` + +If you have an old gcc compiler, try disabling pre-compiled headers like this: +``` +gmake USE_PCH=NO +``` + +### Default install directories: + +| What | Where | +| --- | --- | +| Binaries | /usr/local/bin/ | +| Configuration files | /etc/uhub/ | +| Plugins | /usr/local/lib/uhub/ | +| Manual pages | /usr/local/share/man/man1/ | diff --git a/doc/compile.txt b/doc/compile.txt deleted file mode 100644 index 9084f92a..00000000 --- a/doc/compile.txt +++ /dev/null @@ -1,30 +0,0 @@ -# How to compile: - -## Prerequisites - -Before you try to compile µHub, please make sure the following prerequisites are met. - * GNU make - * gcc > 3.0 (or MinGW on Windows) - * Perl 5 - * openssl > 0.9.8 (or use "make USE_SSL=NO") - * sqlite > 3.x - -For Ubuntu / Debian: - - $ sudo apt-get install cmake make gcc git libsqlite3-dev libssl-dev - -## Linux, Mac OSX, FreeBSD, NetBSD and OpenBSD - - $ cmake . - $ make - % make install - -If you have an old gcc compiler, try disabling pre-compiled headers like this: -gmake USE_PCH=NO - -### Default install directories: - -Binaries /usr/local/bin/ -Configuration files /etc/uhub/ -Plugins /usr/lib/uhub/ -Manual pages /usr/share/man/man1/ diff --git a/doc/getstarted.txt b/doc/getstarted.md similarity index 75% rename from doc/getstarted.txt rename to doc/getstarted.md index 6f0e97ad..b3a456e6 100644 --- a/doc/getstarted.txt +++ b/doc/getstarted.md @@ -2,37 +2,38 @@ ## Compile it at first -See the doc/compile.txt file +See the [compile.md](compile.md) file ## Create configuration files If no configuration files are created, uhub will use the default parameters, so you can skip this step if you are in a hurry to see it run. As root, or use sudo. - - % mkdir /etc/uhub - % cp doc/uhub.conf /etc/uhub - % cp doc/users.conf /etc/uhub - % echo "welcome to uhub" > /etc/uhub/motd.txt +``` +mkdir /etc/uhub +cp doc/uhub.conf /etc/uhub +cp doc/users.conf /etc/uhub +echo "welcome to uhub" > /etc/uhub/motd.txt +``` You can edit the default configuration file before starting uhub. As root edit /etc/uhub/uhub.conf: - +``` hub_name=My Public Hub hub_description=Yet another ADC hub server_port=1511 server_bind_addr=any max_users=150 - +``` ## Start uhub Start the hub in the foreground for the first time. Shut it down, by pressing CTRL+C. - - % uhub - Thu, 05 Feb 2009 00:48:04 +0000 INFO: Starting server, listening on :::1511... - +``` +% uhub +Thu, 05 Feb 2009 00:48:04 +0000 INFO: Starting server, listening on :::1511... +``` Connect to the hub using an ADC client, use the address adc://localhost:1511, or replace localhost with the correct hostname or IP address. **NOTE**: It is important to use the "adc://" prefix, and the port number. @@ -40,43 +41,52 @@ Connect to the hub using an ADC client, use the address adc://localhost:1511, or ## Kill / Stop uhub If you modify the configuration files in /etc/uhub you will have to notify uhub by sending a HUP signal. - - % ps aux | grep uhub - % kill -HUP +``` +ps aux | grep uhub +kill -HUP +``` Or, for the lazy people - - % killall -HUP uhub +``` +killall -HUP uhub +``` ## Start uhub as daemon (or in background mode) In order to run uhub as a daemon, start it with the -f switch which will make it fork into the background. -In addition, use the -l to specify a log file instead of stdout. One can also specify a specific user and/or group, -if one wishes to run uhub as a specific user using the -u and -g switches. -Example: +In addition, use the -l to specify a log file instead of stdout. + +To run uhub as a specific user, use the -u and -g switches. - % uhub -f -l mylog.txt -u nobody -g nogroup +Example: +``` +uhub -f -l mylog.txt -u nobody -g nogroup +``` ## Having more than 1024 users on uhub If you are planning to more than 1024 users on your hub, you must increase the max number of file descriptors allowed. + This limit needs to be higher than the configured max_users in uhub.conf. In Linux can add the following lines to /etc/security/limits.conf (allows for ~4000 users) - * soft nofile 4096 - * hard nofile 4096 +``` +soft nofile 4096 +hard nofile 4096 +``` Or, you can use (as root): - - % ulimit -n 4096 +``` +ulimit -n 4096 +``` ## Interact with uhub through your hub chat (only for operator/admin): You can interact with uhub in your hub main chat using the `!` prefix, followed by a command: Example, to display help and the command you can use: - - * !help - +``` +!help +``` Your mileage may vary -- Good luck! diff --git a/doc/ssl-documentation.txt b/doc/tls-documentation.md similarity index 54% rename from doc/ssl-documentation.txt rename to doc/tls-documentation.md index 3323dc89..b5b03215 100644 --- a/doc/ssl-documentation.txt +++ b/doc/tls-documentation.md @@ -1,18 +1,21 @@ -# Setting up an SSL hub +# Setting up a TLS/SSL hub ## About certificates -Before you can setup an SSL protected hub, you must create an SSL certificate for the hub. -NOTE: uhub must be compiled with SSL support enabled in order for this to work (enabled by default, but not for Windows). +Before you can setup an TLS protected hub, you must create an TLS certificate for the hub. + +NOTE: uhub must be compiled with `SSL_SUPPORT` enabled in order for this to work +(enabled by default, but not for Windows). ## Configuring uhub If you have your certificates ready, just set these configuration values in uhub.conf file: - +``` tls_private_key="/path/to/domainname.key" tls_certificate="/path/to/domainname.crt" tls_enable=yes tls_require=yes +``` Now you can connect to the hub using the adcs:// protocol handle. @@ -21,49 +24,72 @@ Now you can connect to the hub using the adcs:// protocol handle. ### Creating a self-signed certificate To create self-signed certificates with an 2048 bits RSA private key using the following command: - - $ openssl genrsa -out domainname.key 2048 +``` +openssl genrsa -out domainname.key 2048 +``` Then create the certificate (valid for 365 days, using sha256): - - $ openssl req -new -x509 -nodes -sha256 -days 365 -key domainname.key > domainname.crt +``` +openssl req -new -x509 -nodes -sha256 -days 365 -key domainname.key > domainname.crt +``` At this point point you will be prompted a few questions, see the section Certificate data below. ## Creating a certificate with a CA Create an 2048 bits RSA private key using the following command: - - $ openssl genrsa -out domainname.key 2048 +``` +openssl genrsa -out domainname.key 2048 +``` Then create a Certificate Signing Request (csr): - - $ openssl req -new -key domainname.key -out domainname.csr +``` +openssl req -new -key domainname.key -out domainname.csr +``` See the "Certificate data" section below for answering the certificate questions. After this is done, you should send the domainname.csr to your CA for signing, and when the transaction is done you get the certificate from the CA. + Save the certificate as dommainname.crt. ## Certificate data When creating a certificate, you are asked a series of questions, follow this guide: +``` +Two letter country code. + Example: DE. - Two letter country code. Example: DE. - State or Province Name. Example: Bavaria - Locality Name. Example: Munich - Organization Name. The name of your organization or company. Use your name if this certificate is not for any organization) - Organizational Unit Name. The name of your department within your organization, like sysadmin, etc. (can be left blank) - Common Name. The hostname of your server. Example: secure.extatic.org - Your e-mail address +State or Province Name. + Example: Bavaria + +Locality Name. + Example: Munich + +Organization Name. + Use your name if this certificate is not for any organization. + +Organizational Unit Name. + The name of your department within your organization, like sysadmin, etc. + (can be left blank) + +Common Name. + The hostname of your server. + Example: secure.extatic.org + +Your e-mail address. + Example: bob@example.com +``` ## Giving fingerprint -Now that you have ssl activated on your hub, you may have to share the certificate fingerprint to your hub user: +Now that you have tls activated on your hub, you may have to share the certificate fingerprint to your hub user: Find it by using this commandline: - - $ openssl x509 -noout -fingerprint -sha256 < "/path/to/domainname.crt" | cut -d '=' -f 2 | tr -dc "[A-F][0-9]" | xxd -r -p | base32 | tr -d "=" +``` +openssl x509 -noout -fingerprint -sha256 < "/path/to/domainname.crt" \ + | cut -d '=' -f 2 | tr -dc "[A-F][0-9]" | xxd -r -p | base32 | tr -d "=" +``` And give your full uhub address: diff --git a/doc/uhub.spec b/doc/uhub.spec index 397ce007..5a9665ab 100644 --- a/doc/uhub.spec +++ b/doc/uhub.spec @@ -52,12 +52,14 @@ install -m644 doc/init.d.RedHat/etc/sysconfig/uhub $RPM_BUILD_ROOT/etc/sysconfi install -m644 doc/init.d.RedHat/etc/logrotate.d/uhub $RPM_BUILD_ROOT/etc/logrotate.d/ /bin/gzip -9c doc/uhub.1 > doc/uhub.1.gz && install -m644 doc/uhub.1.gz $RPM_BUILD_ROOT/usr/share/man/man1 +/bin/gzip -9c doc/uhub-passwd.1 > doc/uhub-passwd.1.gz && +install -m644 doc/uhub-passwd.1.gz $RPM_BUILD_ROOT/usr/share/man/man1 install -m644 mod_*.so $RPM_BUILD_ROOT/usr/lib/uhub %files %defattr(-,root,root) -%doc AUTHORS BUGS COPYING ChangeLog README TODO doc/Doxyfile doc/architecture.txt doc/compile.txt doc/extensions.txt doc/getstarted.txt doc/uhub.dot +%doc AUTHORS COPYING ChangeLog README.md doc/Doxyfile doc/architecture.txt doc/compile.md doc/extensions.txt doc/getstarted.md doc/uhub.dot doc/motd.txt doc/tls-documentation.md %config(noreplace) /etc/uhub/uhub.conf #%{_sysconfdir}/uhub/uhub.conf %config(noreplace) %{_sysconfdir}/uhub/users.conf