-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.Rmd
160 lines (112 loc) · 6.73 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%",
eval = FALSE
)
```
# proxyconfig
<!-- badges: start -->
[](https://dev.azure.com/cderv/proxyconfig/_build/latest?definitionId=1&branchName=master)
[](https://dev.azure.com/cderv/proxyconfig/_build/latest?definitionId=1&branchName=master)
[](https://dev.azure.com/cderv/proxyconfig/_build/latest?definitionId=1&branchName=master)
[](https://www.tidyverse.org/lifecycle/#experimental)
[](https://CRAN.R-project.org/package=proxyconfig)
[](LICENSE.md)
[](https://travis-ci.com/cderv/proxyconfig)
[](https://codecov.io/gh/cderv/proxyconfig?branch=master)
<!-- badges: end -->
The goal of proxyconfig is to help setting the proxy interactively.
## About proxy configuration
### Why would you need to configure a proxy ?
In a corporate environment, there is often a proxy you need to pass through to
escape your company network. When behind this firewall of your company, you need
to first tell R that it needs to pass the proxy before trying to reach the url
and not to use it when the url you want to access are inside the same network.
### Examples of when it is needed
For example, behind a company proxy,
+ `install.package` won't be able to reach a cran mirror that is outside like `https://https://cloud.r-project.org/`
+ `download.file` won't be able to get a file from a url
+ `httr::GET`, `curl::curl` won't be able to be used for web url.
The first two are R base features and have a `method` argument that you can use to help configure correctly. Different methods can have different settings. The most used is _libcurl_ that is also used by `httr` and `curl` :package:.
### Some words about proxy configuration in R
Sometimes, proxy is automatically picked up by R. It is the case on windows
where R uses the _wininet_ method by default, for which the 'Internet Options',
from Internet Explorer or Edge, are used for proxy configuration.
On other system, proxy must often be explicity configured.
You'll find information about _Setting Proxies_ in R in the `utils::download.file()` help page:
`help("download.file", package = "utils")` or `?download.file`.
## Installation
Currently, this package is only available on Github in development version :
```r
# install.packages("devtools")
devtools::install_github("cderv/proxyconfig")
```
or using
```r
source("https://install-github.me/cderv/proxyconfig")
```
## How to use `proxyconfig`
### How to set the proxy
Given a proxy url, you can set the proxy interactively using `set_proxy` using `proxy` argument. Proxy
url must be of the form _scheme://hostname[:port]_.
```{r set_proxy, eval = FALSE}
proxyconfig::set_proxy(proxy = "http://proxy.mycompany.com:3939")
```
You can also use `options(proxyconfig.proxy = "http://proxy.mycompany.com:3939")`
so that it knows which url to use as default. You can use `usethis::edit_r_profile()` to open the user
_.Rprofile_ and add the option.
Then when in _.Rprofile_, you can call directly
```{r eval = FALSE}
proxyconfig::set_proxy()
```
By default if username and password not provided, this will prompt the user for authentification. You can pass them in `set_proxy` argument too to use non-interactively. **This is not advice to pass them in clear in a script** - this is what the interactive mode with dialog box aims to prevent.
If you don't have any authentification for your proxy, use empty values explicitly.
```{r set_proxy_without_auth, eval = FALSE}
proxyconfig::set_proxy(proxy = "http://proxy.mycompany.com:3939", username = "", password = "")
```
To prevent the proxy to be used for url on internal network domain, use `noproxy` argument. (empty by default). This useful for a github entreprise server or an internal cran repos for example, respectively on `https://github.mycompany.com` and `https://cran.mycompany.com`. Both are on the same domain - `noproxy` is configured here to look for url on domain mycompany.com without exiting the internal pany network through the proxy.
```{r eval = FALSE}
proxyconfig::set_proxy(proxy = "http://proxy.mycompany.com:3939", noproxy = ".mycompany.com")
```
If several domains (or IP addresses) are necessary, they will be concatenated properly.
```{r eval = FALSE}
proxyconfig::set_proxy(proxy = "http://proxy.mycompany.com:3939", noproxy = c(".mycompany.com", "163.104.50.180"))
```
```{r include = FALSE}
# for readme demo - not an example to follow as password is in clear
proxyconfig::set_proxy(proxy = "http://proxy.mycompany.com:3939", username = "its", password = "me", noproxy = c(".mycompany.com", "163.104.50.180"), https = TRUE)
```
### How to check what is configured ?
`set_proxy()` will set the correct environment variable for the current session. You can verify if a proxy is currently configured with `is_proxy_activated()`
```{r check-proxy, eval = FALSE}
proxyconfig::is_proxy_activated()
```
You can have more information using `verbose = TRUE`. (Note that authentification is hidden when printed)
```{r check-proxy-verbose, eval = FALSE}
proxyconfig::is_proxy_activated(TRUE)
```
### What if a proxy is already set ?
If a proxy is already set, `set_proxy` will issue a warning (and return false invisibly)
```{r, eval = FALSE}
(proxyconfig::set_proxy(proxy = "https://newproxy.company.com"))
```
You can unset a proxy configuration with `unset_proxy()`
```{r, eval= FALSE}
proxyconfig::unset_proxy(verbose = TRUE)
# proxy is correctly deactivated
proxyconfig::is_proxy_activated(TRUE)
```
# TODO
This is a very new package that works for me. Among the ideas I have for improvement
- [ ] Use an option mechanism to make the proxy url persistent across sessions
- [ ] Use [keyring](https://github.com/r-lib/keyring) to store and retrieve auth accross session
- [ ] Make a templating system to use proxyconfig in an internal package. Inspiration `ghentr` and `pkgconfig`
- [ ] Improve console output with `cli`
- [ ] Create an add-on for better interactation (and keybinding)