\documentclass[10pt]{article}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%$ Arisa User Documentation: Please Ignore the lines below 
%    (Until the comments say otherwise)
%
%%%% The Following Section is papersize and macro definitions
%%%%    for use in the document below.
%%%% Parsers for the text (other then a LaTeX parser) should
%%%%    ignore the information below except to note the names
%%%%    of the macros being used, and for what purpose.
% Current CVS info: $Id: gettingstarted.tex,v 1.4 2004/05/23 16:55:49 arisa-cvs Exp $
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\topmargin = 0.25in
\headheight = 0in
\headsep = 0in
\textwidth = 6.5in
\oddsidemargin = 0in
\evensidemargin = 0in
\footskip = 0in
\parindent = 0in
\textheight = 9in


%import packages
\usepackage{graphicx}
\usepackage{color}
\usepackage{verbatim}

%Create the note command for nice (ugly) green boxes
\newcommand{\note}[1]{\hspace*{.25in}\colorbox{green}{\begin{minipage}[t]{5.25in}

{\it Note:}

\hspace{.25in} #1
\end{minipage}}\vspace{10pt}}

%Create the warn (warning) command for nice red boxes
\newcommand{\warn}[1]{\colorbox{red}{\begin{minipage}[t]{5.75in}

{\large\bf Warning:}

\hspace{.25in} #1
\end{minipage}}\vspace{10pt}}

%Create the important command for a nice yellow box
\newcommand{\important}[1]{\colorbox{yellow}{\begin{minipage}[t]{5.75in}

{\sc Important:}

\hspace{.25in} #1
\end{minipage}}\vspace{10pt}}

%Create a code verbatim environment for code bits (allows parsing)
\newenvironment{code}[1]{%
   \def\temp{#1}%
   \vspace{10pt}\par\noindent
   \ifx\temp\empty
      \texttt{user@arisabox \$}
   \else
      \texttt{[/#1]----------------------------------------}
   \fi
   \vspace{10pt}%
   \par\noindent\minipage{5.75in}\verbatim}{\endverbatim\endminipage\vspace{10pt}}

%create a dir command to make nice looking dirs ;)
\newcommand{\dir}[1]{[/#1]}

%create a in-paragraph code command
\newcommand{\incode}[1]{{\tt #1}}

%make < and > something easy... lt gt
\newcommand{\gt}{\textgreater}
\newcommand{\lt}{\textless}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%Starting with the next line, this is the actual text of the 
%   Document. Parsers should use the next line to start parsing.
%Begin Parsing%
\begin{document}

\title{Arisa - Getting Started Guide}
\author{Jason Straw, et. al. (See Appendix \ref{authors} for full list)}
\date{Last Revision: 19 May 2004}
\maketitle

Copyright \copyright  2004 Authors (Listed in Appendix \ref{authors}).

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license is available at http://www.gnu.org/licenses/fdl.html .

\section{Getting Arisa}
\subsection{Downloading Arisa}

While in alpha, Arisa is only available in source form at http://www.arisa-chan.org/download.html.  Binaries will be available once Arisa is stable.

\subsection{Compiling Arisa}
To Uncompress the Archive downloaded use the command \incode{tar xjvf arisa-snapshot.tar.bz2}.  Enter the arisa directory (usually of the form \incode{arisa-YYMMDD.HHa}) and run the following commands: 

\begin{code}{}
$ ./configure --with-debug-msg 
$ make
$ su 
# make install
# logout
$
\end{code}

%Begin Note
\note{Shell Prompts: non-root prompt is \$, root is \#.}

\warn{Be Careful as root, and do not run Arisa as root}

We recommend the use of \incode{--with-debug-msg} so that if you need assistance you can provide the correct information.  With the exception of the su command, which will request your root password, these do not take input. They will just output a lot of checks and debug info, as long as you see no errors, you are in good shape.  

If you have configure errors, you should look to see if you can install the package that is being asked for.  If you can not figure out the configure error, or you have compile (make) errors, you should visit the arisa irc channel \#arisa at irc.freenode.net.

\section{Initial Setup}
\subsection{arisa Pre-Config}
Once you have compiled and installed arisa and arisa-sh (which we will get to next section) you can start using your bot.  

The first steps to starting arisa are to create a directory to store configuration, log and data files and to do arisa's preconfig routine.  

\begin{code}{}
$ mkdir config; cd config
$ arisa my_bot.cfg
\end{code}

\note{The name of the config directory and file can be of your choosing.}

Arisa then asks some questions to setup the user interface.

\begin{code}{}
Admin Username: username
Admin Password: 
Admin Password Confirm:
Admin Socket: my_bot.socket
Log File: my_bot.log
\end{code}

\important{The Password / Password Confirm DO NOT show you your password, nor do they show *'s in place of those characters. Both the Username and Password are {\bf Case Sensitive}.}

\note{The Admin Socket is used for the user interface to communicate with arisa.}

\note{These names are all arbitrary, it is suggested that you use \lt configfilename\gt .socket or log to easily discern which file is which. As well, we will continue to refer to the files as my\_bot.socket or log.}

Arisa now enters background mode, and we are ready to really do some configuration.

\section{Configuring arisa with arisa-sh}

arisa-sh is the user interface shell for arisa.  You are able to change all aspects of your config from the arisa-sh interface.  To start arisa-sh:

\begin{code}{}
$ arisa-sh -c my_bot.socket
Username:
username
Password:

>
\end{code}

\note{Although arisa-sh has no actual prompt this document uses '\gt\ ' as the prompt for visual reasons.}

\subsection{General Settings}
Arisa's global general/default settings are stored in the \dir{settings} section.  To access this area use the following commands.

\begin{code}{ }

> settings
> ?
global
help
ignore-list
network
save
\end{code}

\note{? will list the commands available and give general help at any prompt.}

Look around the global and network setting lists of the \dir{settings} section.  Some of the items you may want to change are: 

\begin{description}
\item[hash-packs] This will automatically create CRC32 and MD5 sums of all packs added.
\item[list-frequency] Number of seconds between xdcc lists for any given packlist
\end{description}

Once you are done with global options, type save to tell arisa to add this to the auto-save list. 

\important{Once you type save in a section, you do not have to run save again if you change things later}

Now we go back to the root menu by typing one of the following two lines:

\begin{code}{settings}
> ..
> /
\end{code}

\note{At any time you can use the \incode{/} command to go back to the root of arisa-sh's interface.}

\subsection{Network Interface}

Arisa uses the interface command from \dir{} to access network connections you have available on your system.  Arisa uses three types of interfaces, send, recv, and chat.  A send interface allows arisa to send packs, a recv (receive) interface allows people to upload to arisa (once authenticated), and a chat interface allows for DCC Chat admin of arisa.  Most people only use the send interface.

Interfaces all take the same general format:

\begin{code}{ }
> interface < name of interface> <type>
\end{code}

\note{Replace things inside of  \lt \gt with something of your own choosing.}

Once you have created a send interface, you'll need to at least check over some settings.  The following are the major ones:

\begin{description}
\item[bandwidth] sets a bandwidth limit for everything tied to that interface (in KBytes/second)
\item[advertise-ip] Set this if you are behind a firewall/NAT to your publicly accessible IP that has ports forwarded.  You can check on that at http://www.ipchicken.com 
\item[bind-ip] local IP to bind to. Use this setting if you are using a computer that has multiple public IP addresses. (defaults to any ip on the machine)
\item[dccserver-port] port for mIRC dccserver method 
\item[dcc-port] Start of port range for arisa to use. This is useful if you are behind a firewall and only want to open a small number of ports.
\item[no-ports] Number of ports above 'dcc-port' to use.  This is useful in tandem with 'dcc-port' if you are behind a firewall with x ports in sequence open.
\item[secure-mode] Set this to off if you are on a network with hostmask cloaking.  This checks to see if the person's hostmask is on network before doing anything.
\end{description}

\subsubsection{Bandwidth Pools}

Bandwidth pools are where you set send limits and min/max per send limits. Because an interface can have multiple pools, the pool also has a 'bandwidth' setting like interfaces have. 

To create a pool named pool1 under \dir{interface: s1 (SEND)} use the following:

\begin{code}{ }
> pool pool1
\end{code}

You need to look at have a setting for all of the following

\begin{description}
\item[sends] \# of sends to allow on this pool
\item[bandwidth] Amount of bandwidth (KBytes/second) to allocate to this pool
\item[send-max-bandwidth] Maximum amount of bandwidth any one send can use
\item[send-min-bandwidth] Minimum amount of bandwidth any one send can use
\item[sends-per-user] Number of sends any single person can have at a time
\end{description}

Now, once you are done with the pool, you need to save the pool and the interface by doing the following:

\begin{code}{interface: send1 (SEND)/pool1}
> save
> ..
> save
> /
\end{code}

\note{Like / goes back to \dir{} .. will take you up one level in the configuration system.}

\warn{Although you only need to the when you first create it, you need to save your pool and interface (or any of the other sections) or when you go out of the section you'll lose all of the settings you changed.}

If you want to create another interface just go up to \dir{} and start at the beginning of this section.

\subsection{IRC Networks}

Just like Arisa can have multiple interfaces and pools, it can also have multiple IRC networks that it connects to.  All networks are setup using the network command which has the following format:

\begin{code}{ }
> network <network name>
\end{code}

This will end you up in (assuming you used freenode for your network name) \dir{network: freenode}.  Now you'll want to add some servers with the following command:

\begin{code}{network: <network name>}
> servers add <server> (port)
\end{code}

\note{It is suggested that you use the round-robin (usually irc.network.net) dns AND ips for your network.}

If you didn't change the default settings in general settings, or you want to make adjustments for this network these are settings you'll want to change:

\begin{description}
\item[nick] IRC nick to use (alternate nicks created by rotating letters)
\item[loginname] nick to use for ident (if you aren't running identd)
\item[realname] Real Name field, shows in whois (that's about it)
\item[bind-ip] local IP to bind to. Use this setting if you are using a computer that has multiple public IP addresses.
\item[no-autoconnect] set to on if you want this network to start when arisa does.
\end{description}

Some of the other settings: message-rate, message-rate-max, irc-timeout, reconnect-delay, and join-delay have good default settings for the most part. If you need to change them go for it. If you're having problems with getting excess flood, or reconnecting all the time, check with \#arisa on irc.freenode.net and see if these settings will help.

If you want to identify with nickserv when you connect each time you'll want setup an on-connect command to run.  Most networks have a command called 'ns' that directly connects with nickserv which the first command you see below is.  If that fails to work, try the second command, which should work.

\begin{code}{network: <network name>}
> on-connect add "ns identify <password>"
> on-connect add "PRIVMSG nickserv :identify <password>"
\end{code}

\warn{You need to use quotes around these commands if there is a space in them.  The "on-connect add" command takes one other argument which is the entire command in quotes.}

\subsubsection{Channels}

\begin{code}{network: <network name>}
> channel #<channel name>
> join
\end{code}

The commands above from a network will have arisa join the channel mentioned on that network.  If the channel has a key on it you'll need to set the following 2 settings properly.

\begin{description}
\item[key] Sets the current key for the channel.
\item[track-key] on/off option to allow arisa to keep the correct key in settings, if someone changes the key in channel, arisa will record and save the change.
\end{description}

\important{Remember to save the network and all the channels you create}


\subsection{Setting up Queues}

You have an interface and a bandwidth pool to use with that interface, and arisa connects to some irc network but no-one can get queued to that interface on the irc network.  To allow sends you need a queue that people can join, and this is done with the queue command.

\begin{code}{ }
> queue <name of queue>
\end{code}

You can then set the pool to use with this queue (required), the length of the queue, and how many slots in the queue can be used by any single person with the following settings:

\begin{description}
\item[pool] Sets the bandwidth pool/interface to use (takes 2 arguments \incode{<interface name> <bandwidth pool name>}
\item[length] Sets the length of the queue.
\item[queues-per-user] Sets the number of queue slots any user can use at one time.
\end{description}

\important{Have you saved your queue?}

\section{Packlists}

With a queue made, now you get to the good part, actually created a packlist for people to use.

\begin{code}{ }
> packlist <name of packlist>
> settings queue <name of queue>
\end{code}

The packlist section is one of the most complex sections that you need to work on for a good reason as it is where everything happens. Before you start adding packs, you need to look at some settings.

\begin{description}
\item[dir-scan-interval]  This setting will tell arisa to scan the dirs you add (more info below) every x seconds (3600 is 1 hour, 86400 is 1 day)
\item[retries] Number of times to retry a send before removing
\item[type] How to announce packlist (see below)
\item[list-frequency] This is a packlist level control of how often you can list any given packlist (also set at the global settings level)
\end{description}

The type setting can be one of the following:

\begin{description}
\item[chat] This will open a DCC Chat to do the listing in, allows larger packlists without getting Flooded off the IRC network. ({\bf REQUIRES interface chat})
\item[notice] This is a classic notice setup, just sends regular irc notices to the requester.
\item[tagonly] This only sends the packlist's taglines to the requester (see \ref{taglines} on taglines)
\item[nopacks] Displays interface statistics and taglines, like a 'notice' list type. The difference is that it doesn't actually list the packs. This is useful for if you have a series of files (such as episodes from a tv show) that you have the whole packlist in order.
                                            
\end{description}

\subsubsection{Dirs}
\label{dirs}

Now that a packlist exists, you want to add files for it to do anything... to do that you will need to tell arisa what directories and what files to look at.  The dirs command is what tells arisa what directories are allowed for use in the packlist.

Just using the dirs command without any arguments will list the dirs already added.  Dirs has quite a few optional arguments to it, the major 3 you need to know are add, del and set.  The add argument takes an absolute path to the directory you wish to use (ex \incode{dirs add /home/arisa/stellvia }.) The del argument takes just a number, which corresponds to the list shown by the dirs command (ex \incode{dirs del 1}.) The set command allows you to edit any single line by using the number of that line and a new path to replace with (ex \incode{dirs set 1 /home/arisa/stellvia/avi}.)

\subsubsection{filters}
\label{filters}
The first way to specify packs to add is to create filters that tell arisa what to look for when you tell it to scan for things to add (see \ref{packs} on packs.)

The filter command/arguments work the same as the dirs command (\ref{dirs}.) The filters can take the following 'special' characters in addition to what you normally would use for a filename:

\begin{description}
\item[*] Full Wildcard: This will match between 0 and infinite characters.
\item[?] Single Wildcard: This matches exactly 1 character (and can be repeated)\item[{\color{red} todo}] Are there others?
\end{description}

\subsubsection{packs}
\label{packs}

the packs command allows you to manually add/delete packs like add/remove work in iroffer or it allows you to do almost anything imaginable to the metainfo gathered about the pack.

\begin{code}{Packlist: <packlist name>}
> packs add <file name without path)
> packs del <pack number>
> packs scan 
> packs sort 
\end{code}

Packs scan will scan all the dirs you have entered for any files matching the filters you are using and add them to the list.  Packs sort will sort those packs in alphabetic order by filename, hopefully that will allow you to create lists with eps in numeric order. (Add Tip on tagonly for sequential ordered non-gap packlist in appendix)

\subsubsection{Tag Lines}
\label{taglines}

Tag lines are a powerful user controlled way to allow an arisa bot to give information in packlistings.  They are shown in any packlist format usedb in the order you specify.  Tag lines have the same options and settings as dirs (\ref{dirs}) and filters (\ref{filters}) The output of xdcc listing a tagonly list with 2 taglines (last 2 lines) looks something like this:

\begin{verbatim}
** 13 packs ** 0 of 8 slots open, Queue: 8/8, Record: 697KiB/s **
** Bandwidth Usage ** Current: 200KiB/s, Cap: 200KiB/sec, Record: 1080KiB/s **
** Total Offered: 2.2GiB, Total Transferred: 3.2TiB **
** Serving Gunslinger Girl (Seichi) **
** Replace <number> with the episode number you want, 
       Trigger: /msg Arisa xdcc send gsg #<number> **
\end{verbatim}

\subsubsection{access}

You have created a packlist and all that, but now someone has noticed you're serving stuff in a channel that they don't want served there? how can you tell arisa not to serve that packlist there?

\begin{code}{Packlist: <packlist name>}
> access allow <channel>
> access deny <channel>
> access clone <another packlist to copy the access info from>
> access mode <Allow,Deny, or Smart>
\end{code}

This is pretty self explanatory, except for the access mode part which is explained here:

\begin{description}
\item[Allow] Coming Soon
\item[Deny]  Coming soon
\item[Smart] Coming Soon
\end{description}

\subsubsection{miscellaneous}

The commands below are some smaller commands that may prove extremely useful for controling packlists.

\begin{description}
\item[nolist] a number of minutes to disallow xdcc list to this packlist
\item[nosend] a number of minutes do disallow xdcc sends/queued sends from this packlist
\item[plist]  send a pack list to a channel (takes 2 arguments: \incode{plist <network> <channel>})
\item[queues] queued users from this packlist
\item[rename] rename packlist
\item[sends]  show sends from the interface this packlist uses
\end{description}

\appendix
\section{Tips and Tricks}
To Submit a Tip or trick send an email to arisa at misato dot us

\subsection{tagonly packlists for long packlists (coming soon)}

\section{Acknowledgements}
This work is based on Marcel Klein's Getting Started document that got this all started as well as on Jeff Sloand's arisa command reference.  Thanks also go to the many people from \#arisa at irc.freenode.net and distro members of Sugar-Cube Fansubs (http://www.sugar-cube.org and \#sugar-cube at irc.enterthegame.com) for reading over and testing out this document.

\subsection{Authors}
\label{authors}
Jason Straw \lt arisa at misato dot us \gt\\
Marcel Klein \lt marcel dot klein at koeln dot de\gt\\
Jeff Sloand \lt sakuma at misato dot us \gt
% Coming Soon?: Carl Ritson \lt critson at perlfu dot co dot uk\gt
% Using a link to the FDL rather then posting it all
%\include{fdl}

\end{document}
%End Parsing%
