ncdc(1) ncdc(1) NAME ncdc - Ncurses Direct Connect Client SYNOPSIS ncdc [option...] DESCRIPTION Ncdc is a modern and lightweight direct connect client with a friendly ncurses interface. GETTING STARTED This is a basic introduction for those who are new to ncdc. See the chapters below for a more detailed description of the available functionality. What you see when starting up ncdc is an input line where you can input commands and a log window where the results are displayed, much like a regular terminal. Commands within ncdc start with a slash (e.g. `/help') and have tab completion to help you. The first thing you will want to do after starting ncdc for the first time is to setup some basic information and settings: /set nick MyNick /set description ncdc is awesome! /set connection 10 /share "My Awesome Files" /path/to/files And if you have a direct connection to the internet or if your router allows port forwarding, you may also want to enable active mode: /set active_ip 13.33.33.7 /set active_port 34194 /set active true See the help text for each of the commands and settings for more information. Of course, all of the above settings are saved to the database and will be used again on the next run. To connect to a hub, use /open: /open ncdc adc://dc.blicky.net:2780/ Here `ncdc' is the personal name you give to the hub, and the second argument the URL. This URL will be saved in the database, so the next time you want to connect to this hub, you can simply do: /open ncdc See the help text for '/open' and '/connect' for more information. If you want to automatically connect to a hub when ncdc starts up, use the `autoconnect' setting. Ncdc uses a tabbed interface: every hub opens in a new tab, and there are sev‐ eral other kinds of tabs available as well. The type of tab is indicated in the tab list on the bottom of the screen with a character prefix. Hubs, for example, are prefixed with a `#'. If a tab needs your attention, a colored exclamation mark is displayed before the tab name, different colors are used for different types of activity. Everything else should be fairly self-explanatory: To search for files, use the `/search' command. To browse through the user list of a hub, use `/userlist' or hit Alt+u. To browse someone's file list, use `/browse' or hit the 'b' key in the user list. And to monitor your upload and download connections, use `/con‐ nections' or hit Alt+n. OPTIONS -c, --session-dir= Use a different session directory. Defaults to the contents of the envi‐ ronment variable `$NCDC_DIR' or if this is unset to `$HOME/.ncdc'. -h, --help Display summary of options. -n, --no-autoconnect Don't automatically connect to hubs with the `autoconnect' option set. -v, --version Display ncdc version. INTERACTIVE COMMANDS The following is the list of commands that can be used within ncdc. The /help command can also be used get a list of available commands and to access this documentation. /accept Use this command to accept the TLS certificate of a hub. This command is used only in the case the keyprint of the TLS certificate of a hub does not match the keyprint stored in the database. /browse [[-f] ] Without arguments, this opens a new tab where you can browse your own file list. Note that changes to your list are not immediately visible in the browser. You need to re-open the tab to get the latest version of your list. With arguments, the file list of the specified user will be downloaded (if it has not been downloaded already) and the browse tab will open once it's complete. The `-f' flag can be used to force the file list to be (re-)downloaded. /clear Clears the log displayed on the screen. Does not affect the log files in any way. Ctrl+l is a shortcut for this command. /close Close the current tab. When closing a hub tab, you will be disconnected from the hub and all related userlist and PM tabs will also be closed. Alt+c is a shortcut for this command. /connect [
] Initiate a connection with a hub. If no address is specified, will con‐ nect to the hub you last used on the current tab. The address should be in the form of `protocol://host:port/' or `host:port'. The `:port' part is in both cases optional and defaults to :411. The following protocols are recognized: dchub, nmdc, nmdcs, adc, adcs. When connecting to an nmdcs or adcs hub and the SHA256 keyprint is known, you can attach this to the url as `?kp=SHA256/' Note that this command can only be used on hub tabs. If you want to open a new connection to a hub, you need to use /open first. For example: /open testhub /connect dchub://dc.some-test-hub.com/ See the /open command for more information. /connections Open the connections tab. /disconnect Disconnect from a hub. /gc Cleans up unused data and reorganizes existing data to allow more effi‐ cient storage and usage. Currently, this commands removes unused hash data, does a VACUUM on db.sqlite3, removes unused files in inc/ and old files in fl/. This command may take some time to complete, and will fully block ncdc while it is running. It is recommended to run this command every once in a while. Every month is a good interval. Note that when ncdc says that it has completed this command, it's lying to you. Ncdc will still run a few large queries on the background, which may take up to a minute to com‐ plete. /grant [-list|] Grant someone a slot. This allows the user to download from you even if you have no free slots. The slot will be granted for as long as ncdc stays open or the /ungrant command is used. If you restart ncdc, the user will have to wait for a regular slot. Unless, of course, you /grant a slot again. To get a list of users whom you have granted a slot, use `/grant' without arguments or with `-list'. Be warned that using `/grant' without argu‐ ments on a PM tab will grant the slot to the user you are talking with. Make sure to use `-all' in that case. Note that a granted slot is specific to a single hub. If the same user is also on other hubs, he/she will not be granted a slot on those hubs. /help [|set |keys [
]] To get a list of available commands, use /help without arguments. To get information on a particular command, use /help . To get information on a configuration setting, use /help set . To get help on key bindings, use /help keys. /hset [ []] Get or set per-hub configuration variables. Works equivalent to the `/set' command, but can only be used on hub tabs. /hunset [] This command can be used to reset a per-hub configuration variable back to its global value. /kick Kick a user from the hub. This command only works on NMDC hubs, and you need to be an OP to be able to use it. /me This allows you to talk in third person. Most clients will display your message as something like: ** Nick is doing something Note that this command only works correctly on ADC hubs. The NMDC proto‐ col does not have this feature, and your message will be sent as-is, including the /me. /msg [] Send a private message to a user on the currently opened hub. If no mes‐ sage is given, the tab will be opened but no message will be sent. /nick [] Alias for `/hset nick' on hub tabs, and `/set nick' otherwise. /open [-n] [
] Opens a new tab to use for a hub. The name is a (short) personal name you use to identify the hub, and will be used for storing hub-specific con‐ figuration. If you have specified an address or have previously connected to a hub from a tab with the same name, /open will automatically connect to the hub. Use the `-n' flag to disable this behaviour. See /connect for more information on connecting to a hub. /password This command can be used to send a password to the hub without saving it to the database. If you wish to login automatically without having to type /password every time, use '/hset password '. Be warned, however, that your password will be saved unencrypted in that case. /pm [] Alias for /msg /queue Open the download queue. /quit Quit ncdc. You can also just hit ctrl+c, which is equivalent. /reconnect Reconnect to the hub. When your nick or the hub encoding have been changed, the new settings will be used after the reconnect. This command can also be used on the main tab, in which case all con‐ nected hubs will be reconnected. /refresh [] Initiates share refresh. If no argument is given, the complete list will be refreshed. Otherwise only the specified directory will be refreshed. The path argument can be either an absolute filesystem path or a virtual path within your share. /say Sends a chat message to the current hub or user. You normally don't have to use the /say command explicitly, any command not staring with '/' will automatically imply `/say '. For example, typing `hello.' in the command line is equivalent to `/say hello.'. Using the /say command explicitly may be useful to send message starting with '/' to the chat, for example `/say /help is what you are looking for'. /search [options] Performs a file search, opening a new tab with the results. Available options: -hub Search the current hub only. (default) -all Search all connected hubs, except those with `chat_only' set. -le Size of the file must be less than . -ge Size of the file must be larger than . -t File must be of type . (see below) -tth TTH root of this file must match . File sizes ( above) accept the following suffixes: G (GiB), M (MiB) and K (KiB). The following file types can be used with the -t option: 1 any Any file or directory. (default) 2 audio Audio files. 3 archive (Compressed) archives. 4 doc Text documents. 5 exe Windows executables. 6 img Image files. 7 video Video files. 8 dir Directories. Note that file type matching is done using file extensions, and is not very reliable. /set [ []] Get or set global configuration variables. Use without arguments to get a list of all global settings and their current value. Glob-style pattern matching on the settings is also possible. Use, for example, `/set color*' to list all color-related settings. See the `/hset' command to manage configuration on a per-hub basis. Changes to the settings are automatically saved to the database, and will not be lost after restarting ncdc. To get information on a particular setting, use `/help set '. /share [ ] Use /share without arguments to get a list of shared directories. When called with a name and a path, the path will be added to your share. Note that shell escaping may be used in the name. For example, to add a directory with the name `Fun Stuff', you could do the following: /share "Fun Stuff" /path/to/fun/stuff Or: /share Fun\ Stuff /path/to/fun/stuff The full path to the directory will not be visible to others, only the name you give it will be public. An initial `/refresh' is done automati‐ cally on the added directory. /ungrant [|] Revoke a granted slot. /unset [] This command can be used to reset a global configuration variable back to its default value. /unshare [] To remove a single directory from your share, use `/unshare ', to remove all directories from your share, use `/unshare /'. Note that the hash data associated with the removed files will remain in the database. This allows you to re-add the files to your share without needing to re-hash them. The downside is that the database file may grow fairly large with unneeded information. See the `/gc' command to clean that up. /userlist Opens the user list of the currently selected hub. Can also be accessed using Alt+u. /version Display version information. /whois This will open the user list and select the given user. SETTINGS The following is a list of configuration settings. These settings can be changed and queried using the `/set' command for global settings and `/hset' for hub- local settings. All configuration data is stored in the db.sqlite3 file in the session directory. active Enables or disables active mode. Make sure to set `active_ip' and `active_port' before enabling active mode. active_bind IP address to bind to in active mode. When unset, ncdc will bind to all interfaces. active_ip Your public IP address for use in active mode. It is important that other clients can reach you using this IP address. If you connect to a hub on the internet, this should be your internet (WAN) IP. Likewise, if you connect to a hub on your LAN, this should be your LAN IP. Unlike the other connection-related settings, this can be changed on a per-hub basis, allowing you to have a different public IP address per hub. active_port The listen port for incoming connections in active mode. Set to `0' to automatically assign a random port. If TLS support is available, another TCP port will be opened on the configured port + 1. Ncdc will tell you exactly on which ports it is listening for incoming packets. If you are behind a router or firewall, make sure that you have configured it to forward and allow these ports. autoconnect Set to true to automatically connect to the current hub when ncdc starts up. autorefresh The time between automatic file refreshes. Recognized suffices are 's' for seconds, 'm' for minutes, 'h' for hours and 'd' for days. Set to 0 to disable automatically refreshing the file list. This setting also deter‐ mines whether ncdc will perform a refresh on startup. See the `/refresh' command to manually refresh your file list. backlog When opening a hub or PM tab, ncdc can load a certain amount of lines from the log file into the log window. Setting this to a positive value enables this feature and configures the number of lines to load. Note that, while this setting can be set on a per-hub basis, PM windows will use the global value (global.backlog). chat_only Set to true to indicate that this hub is only used for chatting. That is, you won't or can't download from it. This setting affects the /search command when it is given the -all option. color_* The settings starting with the `color_' prefix allow you to change the interface colors. The following is a list of available color settings: list_default - default item in a list list_header - header of a list list_select - selected item in a list log_default - default log color log_time - the time prefix in log messages log_nick - default nick color log_highlight - nick color of a highlighted line log_ownnick - color of your own nick log_join - color of join messages log_quit - color of quit messages separator - the list separator/footer bar tabprio_low - low priority tab notification color tabprio_med - medium priority tab notification color tabprio_high - high priority tab notification color title - the title bar The actual color value can be set with a comma-separated list of color names and/or attributes. The first color in the list is the foreground color, the second color is used for the background. When the fore- or background color is not specified, the default colors of your terminal will be used. The following color names can be used: black, blue, cyan, default, green, magenta, red, white and yellow. The following attributes can be used: bold, blink, reverse and underline. The actual color values displayed by your terminal may vary. Adding the `bold' attribute usually makes the foreground color appear brighter as well. connection Set your upload speed. This is just an indication for other users in the hub so that they know what speed they can expect when downloading from you. The actual format you can use here may vary, but it is recommended to set it to either a plain number for Mbit/s (e.g. `50' for 50 mbit) or a number with a `KiB/s' indicator (e.g. `2300 KiB/s'). On ADC hubs you must use one of the previously mentioned formats, otherwise no upload speed will be broadcasted. This setting is broadcasted as-is on NMDC hubs, to allow for using old-style connection values (e.g. `DSL' or `Cable') on hubs that require this. description A short public description that will be displayed in the user list of a hub. download_dir The directory where finished downloads are moved to. Finished downloads are by default stored in /dl/. It is possible to set this to a location that is on a different filesystem than the incoming directory, but doing so is not recommended: ncdc will block when moving the completed files to their final destination. download_exclude When recursively adding a directory to the download queue - by pressing `b' on a directory in the file list browser - any item in the selected directory with a name that matches this regular expression will not be added to the download queue. This regex is not checked when adding individual files from either the file list browser or the search results. download_slots Maximum number of simultaneous downloads. email Your email address. This will be displayed in the user list of the hub, so only set this if you want it to be public. encoding The character set/encoding to use for hub and PM messages. This setting is only used on NMDC hubs, ADC always uses UTF-8. Some common values are: CP1250 (Central Europe) CP1251 (Cyrillic) CP1252 (Western Europe) ISO-8859-7 (Greek) KOI8-R (Cyrillic) UTF-8 (International) filelist_maxage The maximum age of a downloaded file list. If a file list was downloaded longer ago than the configured interval, it will be removed from the cache (the fl/ directory) and subsequent requests to open the file list will result in the list being downloaded from the user again. Recognized suffices are 's' for seconds, 'm' for minutes, 'h' for hours and 'd' for days. Set to 0 to disable the cache altogether. flush_file_cache [,...] Tell the OS to flush the file (disk) cache for file contents read while hashing and/or uploading or written to while downloading. On one hand, this will avoid trashing your disk cache with large files and thus improve the overall responsiveness of your system. On the other hand, ncdc may purge any shared files from the cache, even if they are still used by other applications. In general, it is a good idea to enable this if you also use your system for other things besides ncdc, you share large files (>100MB) and people are not constantly downloading the same file from you. hubname The name of the currently opened hub tab. This is a user-assigned name, and is only used within ncdc itself. This is the same name as given to the `/open' command. incoming_dir The directory where incomplete downloads are stored. This setting can only be changed when the download queue is empty. Also see the down‐ load_dir setting. log_debug Log debug messages to stderr.log in the session directory. It is highly recommended to enable this setting if you wish to debug or hack ncdc. Be warned, however, that this may generate a lot of data if you're connected to a large hub. log_downloads Log downloaded files to transfers.log. log_uploads Log file uploads to transfers.log. minislots Set the number of available minislots. A `minislot' is a special slot that is used when all regular upload slots are in use and someone is requesting your filelist or a small file. In this case, the other client automatically applies for a minislot, and can still download from you as long as not all minislots are in use. What constitutes a `small' file can be changed with the `minislot_size' setting. Also see the `slots' config‐ uration setting and the `/grant' command. minislot_size The maximum size of a file that may be downloaded using a `minislot', in KiB. See the `minislots' setting for more information. nick Your nick. Nick changes are only visible on newly connected hubs, use the `/reconnect' command to use your new nick immediately. Note that it is highly discouraged to change your nick on NMDC hubs. This is because clients downloading from you have no way of knowing that you changed your nick, and therefore can't immediately continue to download from you. password Sets your password for the current hub and enables auto-login on connect. If you just want to login to a hub without saving your password, use the `/password' command instead. Passwords are saved unencrypted in the con‐ fig file. sendfile Whether or not to use the sendfile() system call to upload files, if sup‐ ported. Using sendfile() allows less resource usage while uploading, but may not work well on all systems. share_exclude Any file or directory with a name that matches this regular expression will not be shared. A file list refresh is required for this setting to be effective. share_hidden Whether to share hidden files and directories. A `hidden' file or direc‐ tory is one of which the file name starts with a dot. (e.g. `.bashrc'). A file list refresh is required for this setting to be effective. show_joinquit Whether to display join/quit messages in the hub chat. slots The number of upload slots. This determines for the most part how many people can download from you simultaneously. It is possible that this limit is exceeded in certain circumstances, see the `minislots' setting and the `/grant' command. tls_policy Set the policy for secure client-to-client connections. Setting this to `disabled' disables TLS support for client connections, but still allows you to connect to TLS-enabled hubs. `allow' will allow the use of TLS if the other client requests this, but ncdc itself will not request TLS when connecting to others. Setting this to `prefer' tells ncdc to also request TLS when connecting to others. The use of TLS for client connections usually results in less optimal performance when uploading and downloading, but is quite effective at avoiding protocol-specific traffic shaping that some ISPs may do. Also note that, even if you set this to `prefer', TLS will only be used if the connecting party also supports it. ui_time_format The format of the time displayed in the lower-left of the screen. Set `-' to not display a time at all. The string is passed to the Glib g_date_time_format() function, which accepts roughly the same formats as strftime(). Check out the strftime(3) man page or the Glib documentation for more information. Note that this setting does not influence the date/time format used in other places, such as the chat window or log files. KEY BINDINGS On any tab without the text input line, you can press `?' to get the key bind‐ ings for that tab. The list of key bindings is available through the `/help keys' command, and is reproduced below. Global key bindings Alt+j Open previous tab. Alt+k Open next tab. Alt+h Move current tab left. Alt+l Move current tab right. Alt+ Open tab with number . Alt+c Close current tab. Alt+n Open the connections tab. Alt+q Open the download queue tab. Alt+o Open own file list. Alt+r Refresh file list. Ctrl+c Quit ncdc. Keys for tabs with a log window: Ctrl+l Clear current log window. PgUp Scroll the log backward. PgDown Scroll the log forward. Keys for tabs with a text input line: Left/Right Move cursor one character left or right. End/Home Move cursor to the end / start of the line. Up/Down Scroll through the command history. Tab Auto-complete current command, nick or argument. Alt+b Move cursor one word backward. Alt+f Move cursor one word forward. Backspace Delete character before cursor. Delete Delete character under cursor. Ctrl+w Delete to previous space. Alt+d Delete to next space. Ctrl+k Delete everything after cursor. Ctrl+u Delete entire line. File browser Up/Down Select one item up/down. k/j Select one item up/down. PgUp/PgDown Select one page of items up/down. End/Home Select last/first item in the list. Right/l Open selected directory. Left/h Open parent directory. o Toggle sorting directories before files. s Order by file size. n Order by file name. d Add selected file/directory to the download queue. m Match selected item with the download queue. M Match entire file list with the download queue. a Search for alternative download sources. Connection list Up/Down Select one item up/down. k/j Select one item up/down. PgUp/PgDown Select one page of items up/down. End/Home Select last/first item in the list. d Disconnect selected connection. i/Return Toggle information box. f Find user in user list. q Find file in download queue. Download queue Up/Down Select one item up/down. k/j Select one item up/down. PgUp/PgDown Select one page of items up/down. End/Home Select last/first item in the list. K/J Select one user up/down. f Find user in user list. c Find connection in the connection list. a Search for alternative download sources. d Remove selected file from the queue. +/- Increase/decrease priority. i/Return Toggle user list. r Remove selected user for this file. R Remove selected user from all files in the download queue. x Clear error state for the selected user for this file. X Clear error state for the selected user for all files. Note: when an item in the queue has `ERR' indicated in the priority col‐ umn, you have two choices: You can remove the item from the queue using `d', or attempt to continue the download by increasing its priority using `+'. Search results tab Up/Down Select one item up/down. k/j Select one item up/down. PgUp/PgDown Select one page of items up/down. End/Home Select last/first item in the list. f Find user in user list. b/B Browse the selected users' list, B to force a redownload. d Add selected file to the download queue. h Toggle hub column visibility. u Order by username. s Order by file size. l Order by free slots. n Order by file name. m Match selected item with the download queue. M Match all search results with the download queue. q Match selected users' list with the download queue. Q Match all matched users' lists with the download queue. a Search for alternative download sources. User list tab Up/Down Select one item up/down. k/j Select one item up/down. PgUp/PgDown Select one page of items up/down. End/Home Select last/first item in the list. o Toggle sorting OPs before others. s/S Order by share size. u/U Order by username. t/T Toggle visibility / order by tag column. e/E Toggle visibility / order by email column. c/C Toggle visibility / order by connection column. p/P Toggle visibility / order by IP column. i/Return Toggle information box. m Send a PM to the selected user. g Grant a slot to the selected user. b/B Browse the selected users' list, B to force a redownload. ENVIRONMENT $NCDC_DIR is used to determine the session dir, it is only honoured if -c is not set on the command line. FILES $NCDC_DIR corresponds to the session dir set via -c, environment variable $NCDC_DIR or $HOME/.ncdc. $NCDC_DIR/cert/ Directory where the client certificates are stored. Must contain a pri‐ vate key file (client.key) and public certificate (client.crt). These should be generated automatically when ncdc starts up the first time, but can be generated manually using ncdc-gen-cert(1). $NCDC_DIR/db.sqlite3 The database. This stores all configuration variables, hash data of shared files, download queue information and other state information. Manually editing this file with the `sqlite3' commandline tool is possi‐ ble but discouraged. Any changes made to the database while ncdc is run‐ ning will not be read, and may even get overwritten by ncdc. $NCDC_DIR/dl/ Directory where completed downloads are moved to by default. Can be changed with the `download_dir' configuration option. $NCDC_DIR/files.xml.bz2 Filelist containing a listing of all shared files. $NCDC_DIR/fl/ Directory where downloaded file lists from other users are stored. The names of the files are hex-encoded user IDs that are used internally by ncdc. Old file lists are deleted automatically after a configurable interval. See the `filelist_maxage' configuration option. $NCDC_DIR/history Command history. $NCDC_DIR/inc/ Default location for incomplete downloads. Can be changed with the `incoming_dir' setting. The file names in this directory are the base32-encoded TTH root of the completed file. $NCDC_DIR/logs/ Directory where all the log files are stored. File names starting with `#' are hub logs and `~' are user (PM) logs. Special log files are trans‐ fers.log and main.log. ncdc does not have built-in functionality to rotate or compress log files automatically. When rotating log files manually (e.g. via a cron job), make sure to send the SIGUSR1 signal afterwards to force ncdc to flush the old logs and create or open the new log files. $NCDC_DIR/stderr.log Error/debug log. This file is cleared every time ncdc starts up. $NCDC_DIR/version Version of the data directory. This file locked while an ncdc instance is running, making sure that no two ncdc instances work with the same ses‐ sion directory at the same time. LICENSE Copyright (C) 2011 Yoran Heling ncdc is distributed under the MIT license, please read the COPYING file for more information. BUGS Please report bugs or feature requests to projects@yorhel.nl or connect to the development hub at adc://dc.blicky.net:2780/. AUTHOR ncdc is written by Yoran Heling Web: http://dev.yorhel.nl/ncdc SEE ALSO ncdc-gen-cert(1), ncdc-db-upgrade(1). ncdc-1.7 December 2011 ncdc(1)