Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

man page needed #120

Closed
ghost opened this issue Mar 20, 2019 · 8 comments

Comments

Projects
None yet
1 participant
@ghost
Copy link

commented Mar 20, 2019

I noticed in the issues --proxy-server= is an option that can be passed to electron-mail. It would really be useful if man electron-mail would show that, and also mention file locations like the database.bin (which will apparently be in $HOME/.config/electron-mail/ having dug through some of the issues threads). That's important for firejail users, because they need to know the file locations to whitelist before they launch the app.

@vladimiry

This comment has been minimized.

Copy link
Owner

commented Mar 20, 2019

I don't think man page is needed, this is not a CLI program. But I'm going to tweak the readme file listing there data/config files the app is creating and using:

  • config.json file keeps config parameters. There is no sensitive data in this file, so unencrypted.
  • settings.bin file keeps added to the app accounts with credentials. The file is encrypted with 32 bytes length key derived from master password.
  • database.bin file is a local database that keeps fetched emails/folders/contacts if the local store feature is enabled for at least one account. The file is encrypted with 32 bytes length key randomly generated and stored in settings.bin.
  • log.log - log file.

Anything else if any in the settings directory can be safely removed.

@vladimiry

This comment has been minimized.

Copy link
Owner

commented Mar 20, 2019

I noticed in the issues --proxy-server= is an option that can be passed to electron-mail. It would really be useful if man electron-mail would show that

Electron is using Chromium so you can try passing to the app a lot of different arguments not only the --proxy-server one https://duckduckgo.com/?q=Chromium+Command+Line+Switches

Also, since v3.0.0 the app supports configuring proxy per account via the UI (account add/edit form).

@vladimiry

This comment has been minimized.

Copy link
Owner

commented Mar 22, 2019

Referencing the issue with --proxy-server="http://127.0.0.1:8118" usage example #79 (app-wide proxy configuring).

@vladimiry

This comment has been minimized.

Copy link
Owner

commented Mar 22, 2019

The readme file has just been updated.

@vladimiry vladimiry closed this Mar 22, 2019

@ghost

This comment has been minimized.

Copy link
Author

commented Mar 22, 2019

Thanks for the update. It is useful to have the files of interest documented.

Before a user runs an app for the first time, they don't know what to expect. They don't know if the app needs to be forced into a tor environment, or if the app is configurable for tor. Launching an app with torsocks would be the safe thing to do not knowing how the app connects. But this can still be a problem:

  • if the app detects tor and tries to use it (e.g. Wire), then it will attempt to connect to localhost port 9050 (for example) when it's already been constrained to WAN connections via tor.
  • if it's a java app, things get really dicey because torsocks does not work correctly with java apps that aren't designed for tor
  • apps can still leak data despite torsocks, because they can ignore the LD_LIBRARY variable.
  • if an app needs to connect to local sockets (e.g. connect to a local SMTP server to send mail), then torsocks and middleboxing it will break it (unless care is taken to NAT ports on the middlebox).

Some apps are tor-capable, but leak like crazy, in which case their proxy setting should not be used and they should be firejailed.

If things launch in a broken way because the user guessed wrong on whether to use torsocks, then they wonder if initial config files were correctly generated.

So doing a man program is the standard way users discover things before the run something for the first time. Users might even forget what electron-mail is if they don't use it for a while and do a man electron-mail to get a quick reminder on its basic purpose.

I don't mean to task you or be pushy.. but I have to say the idea that a man page has no value is unconventional. Users can dig through github issues to get some of this info but it's not the typical approach.

When you say Electron is using Chromium, that's an important bit of info for a user to know before launching. I happen to have Ungoogled Chromium installed, and now I wonder what if I didn't - would electron-mail fail to launch? The man page should say that there is a dependency on Chromium and that Chromium CLI options are passed through.

Note as well that the .deb file installation created /usr/share/doc/electron-mail/, but the README.md didn't get copied there (only the change log). So someone who installs the deb file apparently needs to find the github project.

@vladimiry

This comment has been minimized.

Copy link
Owner

commented Mar 23, 2019

The thing is that I'm not good at keeping the documentation up to date even if that's a single readme file. But you are proposing introducing a second documentation entry point. So I'm not going to add a man page but would accept a complete pull request. Complete means that the man page would be properly integrated into the every currently shipped Linux package. I would also expect someone would keep the man page up to date otherwise adding it would not make much sense.

Regarding Tor, I saw people also use Whonix Workstation, see this issue. So there is a lot of ways Tor can be used and that would be up to a user which option to go with. I think recommending a specific way of using Tor would be outside of the scope of developing the app.

Electron is using Chromium

Electron uses Chromium as a built-in thing, so it doesn't depend on the system-wide installation if any.

@ghost

This comment has been minimized.

Copy link
Author

commented Mar 23, 2019

Indeed the docs should be maintained and preferably not by you so you can focus on the functionality.

The update anomaly can be remedied by generating docs.

I think the only thing left to say is that Debian requires a separate man page for every program. So if at some point Electron Mail were to seek inclusion in an official Debian repository there would be no choice at that point. And note as well that being official Debian is a good goal to have. When a project is in official Debian repos it becomes noticed and spreads faster because it's proven to have reached a good quality standard.

Regarding Tor, thread #113 is interesting; thanks. My knee-jerk thought is what happens when Chromium's --proxy-server= is passed when the accounts have separate proxies? Hopefully the account-specific configs take precedence and the global setting is used only when the account-specific proxy is null.

BTW, #113 relates to a feature request I've been planning to file, which would entail logins being triggered by tab focus, not by program launch.

@vladimiry

This comment has been minimized.

Copy link
Owner

commented Mar 23, 2019

I the man page to be added I'd prefer it to be automatically generated from the readme file, so there would be a single source of truth. I would then add the man page generating script to the build pipeline.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.