# LocalPac [![Build Status](https://travis-ci.org/dg-vrnetze/local_pac.png?branch=master)](https://travis-ci.org/dg-vrnetze/local_pac) [![Code Climate](https://codeclimate.com/github/dg-vrnetze/local_pac.png)](https://codeclimate.com/github/dg-vrnetze/local_pac) [![Coverage Status](https://coveralls.io/repos/dg-vrnetze/local_pac/badge.png?branch=master)](https://coveralls.io/r/dg-vrnetze/local_pac?branch=master) [![Gem Version](https://badge.fury.io/rb/local_pac.png)](http://badge.fury.io/rb/local_pac) `local_pac` *serves two main purposes:* 1. Serve proxy.pac-files compressed from a git repository. 2. Lookup of url in proxy.pac to find out which proxy will be used. *Behind the scenes it uses ...* * a javascript compressor ([uglifier](https://github.com/lautis/uglifier)) * a proxy-pac parser ([ruby-pac](https://github.com/samuelkadolph/ruby-pac)) * a vcs library ([rugged](https://github.com/libgit2/rugged)) * etc. *Possible use cases:* * Administrator serving proxy.pacs to thousands of clients * Internal developer using virtual machines on her laptop to develop web applications but who still needs access to external web applications via internal proxy * Developer/Consultant using a vpn connection to her customer + internal proxy/socks proxy, but still needs direct access to the internet web applications * Supporter who needs to support thousand of clients and needs to check which internal proxies is used for a given url * Curious people loving git and using it for every possible use case ;-) ## Screenshots *Search for a url* ![Search for a url](https://raw2.github.com/dg-vrnetze/gh-local_pac/gh-pages/images/screenshot_1.png) *Pretty result for a url* ![Pretty result for a url](https://raw2.github.com/dg-vrnetze/gh-local_pac/gh-pages/images/screenshot_2.png) *Raw result for a url* ![Raw result for a url](https://raw2.github.com/dg-vrnetze/gh-local_pac/gh-pages/images/screenshot_3.png) ## Installation ### RubyGems Add this line to your application's Gemfile: gem 'local_pac' And then execute: $ bundle Or install it yourself as: $ gem install local_pac ### Arch Linux ```bash # Install via yaourt yaourt -S local_pac # Install via cower + makepkg cower -d local_pac cd makepkg -is ``` ## Usage ### Quickstart *Initialize local_pac* ``` % local_pac init --pre-seed ``` *Starting Webserver* ``` % local_pac serve ``` *Download proxy.pac on commandline* ``` % curl --noproxy "*" http://localhost:8000/v1/pac/proxy.pac ``` *Starting webbrowser and open web application* ``` % firefox http://localhost:8000/v1/lookup/proxy.pac ``` ### Getting started (Work in Progress) Make sure that you place a config file for `local_pac` in one of the following places or let `local_pac` generate a file on default values (see below). * `$HOME/.config/local_pac/config.yaml` * `$HOME/.local_pac/config.yaml` * `/etc/local_pac/config.yaml`
Table 1: Configuration values for local_pac
Option Default value Description
:local_storage $HOME/.local/share/local_pac/data/storage.git Path to git-(bare)-repository to store the proxy.pac-files. This is not for direct use!
:executable /path/to/gem/bin/local_pac Internal use only
:pid_file $HOME/.local/share/local_pac/run/pid If would do not use `systemd`, but want to run `local_pac` as a system service, you might need a pid file for your init-daemon.
:gem_path `ruby -rrubygems -e 'puts Gem.path.join(", ")'` Internal use only
:access_log $HOME/home/xgvndeg/.local/share/local_pac/log/access.log Write access to the file in production and test environment.
:sass_cache $HOME/home/xgvndeg/.local/share/local_pac/cache Cache for assets for the lookup of urls
:config_file No default Internal use only
A config file could look like the following one: ```yaml :local_storage: /var/local_pac/data/storage.git :pid_file: /run/local_pac/pid :access_log: /var/log/local_pac/access.log :sass_cache: /var/local_pac/cache ``` After creating creating that file, you can check it by running `local_pac status --config-file `. If your file could be parsed successfully, you can initialize the `local_pac`-environment by running `local_pac initialize --config-file ` or `local_pac initialize`. The latter works only if you placed your config file at one of the known paths mentioned above. The next step is to clone the newly created repository - e.g. at `/home//.local/share/data/storage.git`. Summary: 1. Create a config file 2. Check config file 3. Initialize `local_pac` 4. Clone `local_pac`-git-repository 5. Add a proxy.pac to git-repository 6. Push to `local_pac`-git-repository 7. Restart `local_pac`-service ### Serving proxy.pacs You need to place your proxy.pac in one of the following directories: * $HOME/.config/pacfiles/ * $HOME/.pacfiles/ Otherwise the gem will use it's default proxy.pac: ```javascript function FindProxyForURL(url, host) { return "DIRECT"; } ``` After storing your proxy.pac-files you can serve them via: ```bash local_pac serve # Output: # [2014-02-11 14:30:51] INFO WEBrick 1.3.1 # [2014-02-11 14:30:51] INFO ruby 1.9.3 (2013-11-22) [x86_64-linux] # == Sinatra/1.4.4 has taken the stage on 8000 for development with backup from WEBrick # [2014-02-11 14:30:51] INFO WEBrick::HTTPServer#start: pid=2295 port=8000 ``` After that you need to point your browser to your proxy.pac: ``` http://localhost:8000/v1/pac/.pac ``` If you want to use it in a larger deployment, you might want to use the systemd-files provided by the gem: * share/system/local_pac.socket * share/system/local_pac.service There are some options supported by `serve`. Please use `local_pac help serve` to get a full and up-to-date overview. ``` $ local_pac help serve Usage: local_pac serve Options: [--access-log=ACCESS_LOG] # File to write access log to [--port=N] # The port the server listens on # Default: 8000 [--config-file=CONFIG_FILE] # Config file [--log-level=LOG_LEVEL] # Log level for ui logging ``` ### Initialize environment To initialize your environment, you can use `local_pac init`. To overwrite existing files add the `--force`-flag: `local_pac init --force`. ``` $ local_pac init W, [2014-02-14T12:52:41.980670 #5343] WARN -- : Repository "/home/user/.local/share/local_pac/run" already exists. Do not create it again!. W, [2014-02-14T12:52:41.983601 #5343] WARN -- : Repository "/home/user/.local/share/local_pac/log" already exists. Do not create it again!. W, [2014-02-14T12:52:41.986188 #5343] WARN -- : Repository "/home/user/.local/share/local_pac/data" already exists. Do not create it again!. W, [2014-02-14T12:52:41.988631 #5343] WARN -- : File "/home/user/.local/share/local_pac/data/hooks/pre-receive" already exists. Do not create it again!. ``` ### Config variables To make debugging a little bit easier you can view the config values used by `local_pac` by running `local_pac config`. ```bash option | value -------------------- + -------------------------------------------------------------------------------- access_log | /home/user/.local/share/local_pac/log/access.log local_storage | /home/user/.local/share/local_pac/data pid_file | /home/user/.local/share/local_pac/run/pid gem_path | /home/user/.gem/ruby/1.9.3, /opt/rubies/1.9.3/lib/ruby/gems/1.9.1 ``` ## Reading A good website to support you writing proxy.pac-files is: http://findproxyforurl.com. ## Documentation http://www.rubydoc.info/github/dg-vrnetze/local_pac/frames ## Future * Improve API to support further functionality ## Development Please read the developer documentation `README.DEVELOPER.md`. ## Copyright 2014, Dennis Günnewig (VR Netze GmbH, http://www.vrnetze.de) ## Contributing 1. Fork it ( http://github.com//local_pac/fork ) 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create new Pull Request