mirror of
https://github.com/psforever/PSF-LoginServer.git
synced 2026-01-19 18:44:45 +00:00
scram-sha-256 (#1003)
* jasync updated to support scram-sha-256; README.md updated * added README section about becoming a gm; moved a section of the README
This commit is contained in:
Fate-JH
GitHub
parent
229777559f
commit
a246fd1244
255
README.md
255
README.md
|
|
@ -7,10 +7,10 @@ it upon ourselves to preserve PlanetSide 1's unique gameplay and history _foreve
|
|||
|
||||
The login and world servers (this repo runs both by default) are built to work with PlanetSide version 3.15.84.0.
|
||||
Anything older is not guaranteed to work. Currently, there are no binary releases of the server as the state is
|
||||
pre-alpha. You will need to have a development environment set up in order to get it running. If you just want to play,
|
||||
you don't need to set up a development environment. Join the public test server by following the _[PSForever Server
|
||||
Connection Guide](https://docs.google.com/document/d/1ZMx1NUylVZCXJNRyhkuVWT0eUKSVYu0JXsU-y3f93BY/edit)_, which has the
|
||||
instructions on downloading the game and using the PSForever launcher to start the game.
|
||||
~~pre-alpha~~ ~~alpha~~ ~~beta~~ scare. To contribute, you will need to have a development environment in order to get it running.
|
||||
If you just want to play, you don't need the development environment. Join the public test server by following
|
||||
the _[PSForever Server Connection Guide](https://docs.google.com/document/d/1ZMx1NUylVZCXJNRyhkuVWT0eUKSVYu0JXsU-y3f93BY/edit)_,
|
||||
which has the instructions on downloading the game and using the PSForever launcher to start the game.
|
||||
|
||||
<p align="center">
|
||||
<kbd>
|
||||
|
|
@ -20,208 +20,233 @@ instructions on downloading the game and using the PSForever launcher to start t
|
|||
</p>
|
||||
|
||||
## Server Requirements
|
||||
- Running
|
||||
- [Java](https://www.java.com/en/) Development Kit 8.0
|
||||
- JDK 1.8_251
|
||||
- [Scala](https://www.scala-lang.org/)
|
||||
- 2.13.3 (set in `build.sbt`)
|
||||
- [sbt](http://www.scala-sbt.org) (Scala build tool)
|
||||
- 1.4.5+?
|
||||
- Up to date
|
||||
- [PostgreSQL](https://www.postgresql.org/)
|
||||
- 10+
|
||||
- Development (+Running)
|
||||
- [Git](https://en.wikipedia.org/wiki/Git)
|
||||
- IDE or Text Editor
|
||||
|
||||
- sbt (Scala build tool)
|
||||
- Java Development Kit (JDK) 8.0
|
||||
- PostgreSQL
|
||||
### Git
|
||||
Git means "Global Information Tracker" and is used for project revision control, keeping track of changes made to
|
||||
files. Git is not actually necessary to acquire the project as GitHub allows for downloading a ZIP
|
||||
archive of the source code that can be deployed anywhere. Development on the project, however, will require the
|
||||
use of GitHub and, as recommended, a fork of the main project repository.
|
||||
|
||||
## Setting up a Build Environment
|
||||
PSF-LoginServer is writen in [Scala](https://www.scala-lang.org/) and built using sbt, which allows it to be built on
|
||||
Though git is traditionally a command line interface (CLI) application, GitHub offers a [Desktop](https://desktop.github.com/)
|
||||
GUI that introduces graphical components and menus for normal operations, as well as visualization of the revision
|
||||
hierarchy itself. Depending on the Linux distro, users have access to the git CLI through a [variety](https://git-scm.com/download/linux)
|
||||
of commands. For Windows, use an [appropriate installer](https://git-scm.com/download/win) for the CLI. Additionally,
|
||||
[posh-git](https://git-scm.com/book/en/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-PowerShell) exists to make
|
||||
the CLI prettier and more informative for Windows PowerShell users.
|
||||
|
||||
Your IDE of choice may also be integrated with git. Check its documentation.
|
||||
|
||||
Use `git clone https://github.com/[user]/PSF-LoginServer.git`, where "user" is your GitHub account or `psforever` for
|
||||
the main project, to create a local copy. If the main project, you should not use the produced local repository
|
||||
for developmental purposes - fork it first and `git clone` that. One way or another, an installation directory of
|
||||
the project will have been created.
|
||||
|
||||
### Languages
|
||||
PSF-LoginServer is written in Scala and built using sbt which allows it to be built on
|
||||
any platform. sbt is the Scala version of Make, but is more powerful as build definitions are written in Scala. sbt is
|
||||
distributed as a Java JAR and the only dependency it has is a JDK. [Follow the quick instructions on Scala's home
|
||||
page](https://www.scala-lang.org/download/) to get a working development environment and come back when you are done.
|
||||
distributed as a Java JAR and the only dependency it has is a JDK. In order to compile scala, `scalac` is used behind
|
||||
the scenes. This is equivalent to Java's `javac`, and the language itself runs on top of the Java Virtual
|
||||
Machine, meaning it generates `.class` and `.jar` files and uses the `java` executable. Essentially, Scala is just a
|
||||
compiler that targets a JVM runtime.
|
||||
|
||||
In order to compile scala, `scalac` is used behind the scenes. This is equivalent to Java's `javac`, but for the Scala
|
||||
language. Scala runs on top of the Java Virtual Machine, meaning it generates `.class` and `.jar` files and uses the
|
||||
`java` executable. Essentially, Scala is just a compiler that targets the JVM, which is its runtime. All of this runs in
|
||||
the background and is packaged automatically by your IDE or sbt, which automatically downloads the right version of the
|
||||
Scala compiler for you.
|
||||
Download and install the
|
||||
[correct version](https://www.oracle.com/java/technologies/javase/javase8u211-later-archive-downloads.html) of Java,
|
||||
a more [up-to-date version](https://www.oracle.com/java/technologies/downloads/) of Java (if you don't have one),
|
||||
then follow the [quick instructions on Scala's home page](https://www.scala-lang.org/download/)
|
||||
to get a working development environment. The modern installation of Scala utilizes Coursier, a Scala application
|
||||
used for dependency resolution, and will install a number of "apps" including the sbt build tool. These "apps" are
|
||||
always installed with the most-recent non-developmental versioning, so follow the
|
||||
[command guidelines](https://get-coursier.io/docs/cli-install) to install the version that is wanted or
|
||||
required. Additionally, specific releases of Scala can also be installed separately.
|
||||
|
||||
If you have Docker and docker-compose installed on your system, you can get a complete development environment up by
|
||||
running `docker-compose up` in the source code directory. Otherwise, keep reading.
|
||||
|
||||
### Using an IDE
|
||||
### sbt
|
||||
As mentioned, when acquiring the Scala language using Coursier, a version of sbt will also be added.
|
||||
If not using Coursier, download [sbt for your platform](http://www.scala-sbt.org/download.html) and install or
|
||||
extract it. Open up a command line tool - cmd.exe, bash, CYGWIN, Git Bash - that has the Java Development Kit
|
||||
accessible from prompt to use `sbt` commands.
|
||||
|
||||
Scala code can be fairly complex, and a good IDE helps you understand the code and what methods are available for certain
|
||||
types, especially as you are learning the language. IntelliJ IDEA has some of the most mature support for Scala of any
|
||||
IDE today. It has advanced type introspection and excellent code completion. It's recommended for those who are new to
|
||||
Scala in order to get familiar with the syntax.
|
||||
Note: sbt is quite slow at starting up due to JVM JIT warmup. An open sbt console - just run `sbt` without any
|
||||
arguments - is recommended in order to avoid this startup time.
|
||||
|
||||
[Download the community edition of IDEA](https://www.jetbrains.com/idea/download/) directly from IntelliJ's website.
|
||||
[Then get the required Scala plugin for IDEA](https://www.jetbrains.com/help/idea/managing-plugins.html).
|
||||
### PostgreSQL Database
|
||||
A database is required for persistence of game state and player characters. The login server and game server (which are
|
||||
considered the same things, more or else) are set up to accept queries to a PostgreSQL server. It doesn't matter if you
|
||||
don't understand what PostgreSQL actually is compared to MySQL. I don't get it either - just install it:
|
||||
for [Windows](https://www.postgresql.org/download/windows/);
|
||||
for Linux [Debian](https://www.postgresql.org/download/linux/debian/),
|
||||
for Linux [Ubuntu](https://www.postgresql.org/download/linux/ubuntu/);
|
||||
or, for macOS, [normally](https://www.postgresql.org/download/),
|
||||
or using`brew install postgresql && brew net.psforever.services start postgresql`.
|
||||
|
||||
Next, you need to get a copy of the LoginServer code. It's recommended that you perform a `git clone
|
||||
https://github.com/psforever/PSF-LoginServer.git` using your favorite git tool. You can also work from a downloaded ZIP
|
||||
of the source, but you cannot track/commit your changes.
|
||||
|
||||
Once you have the code downloaded, you will need to import the project into the IDE. Follow these instructions from
|
||||
[IntelliJ to import an sbt
|
||||
project](https://docs.scala-lang.org/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.html).
|
||||
Once you have successfully imported the project ([and setup the DB](#setting-up-the-database)), create a new run
|
||||
configuration with the `server/run` sbt task and click run to launch the server.
|
||||
|
||||
### Using sbt and a Text Editor
|
||||
|
||||
If you are not a fan of big clunky IDEs (IDEA is definitely one of them), you can opt to use your favorite text editor
|
||||
(VSCode, Sublime, ViM, Notepad++, Atom, etc.) and use sbt to build the project. The only dependency you will need is sbt
|
||||
itself. [Download sbt](http://www.scala-sbt.org/download.html) for your platform, install or extract, and open up a
|
||||
command line (cmd.exe, bash, CYGWIN, Git Bash) that has the Java Development Kit in its path.
|
||||
|
||||
At the command line run the following commands:
|
||||
|
||||
```
|
||||
git clone https://github.com/psforever/PSF-LoginServer.git
|
||||
cd PSF-LoginServer
|
||||
sbt server/run
|
||||
```
|
||||
This will clone the repository and sbt will compile and run the login server ([make sure you have set up the
|
||||
DB](#setting-up-the-database)). Note: sbt is quite slow at starting up (JVM/JIT warmup). It's recommended you have an
|
||||
open sbt console (just run `sbt` without any arguments) in order to avoid this startup time. With a sbt console you can
|
||||
run tests (and you should) using `sbt test`.
|
||||
|
||||
## Setting up the Database
|
||||
|
||||
The Login and World servers require PostgreSQL for persistence.
|
||||
|
||||
- Windows - [Official Downloads](https://www.postgresql.org/download/windows/)
|
||||
- Linux - [Debian](https://www.postgresql.org/download/linux/debian/) or [Ubuntu](https://www.postgresql.org/download/linux/ubuntu/)
|
||||
- macOS - Application https://www.postgresql.org/download/ (or `brew install postgresql && brew net.psforever.services start postgresql`)
|
||||
|
||||
The default database is named `psforever` and the credentials are `psforever:psforever`. To change these, create a
|
||||
configuration file at `config/psforever.conf`. For configuration options and their defaults, see
|
||||
[`application.conf`](/src/main/resources/application.conf). The database user will need ALL access to tables, sequences,
|
||||
and functions. The permissions required can be summarized by the SQL below. Loading this in requires access to a
|
||||
graphical tool such as [pgAdmin](https://www.pgadmin.org/download/) (highly recommended) or a PostgreSQL terminal
|
||||
(`psql`) for advanced users.
|
||||
|
||||
To get started using pgAdmin, run the binary. This will start the pgAdmin server and pop-up a tab in your web browser
|
||||
with the interface. Upon first run, enter your connection details that you created during the PostgreSQL installation.
|
||||
When connected, right click the "Databases" menu -> Create... -> Database: psforever -> Save. Next, right click on the
|
||||
newly created database (psforever) -> Query Tool... -> Copy and paste the commands below -> Hit the "Play/Run" button.
|
||||
The user should be created and made owner of the database.
|
||||
Additionally, loading the database information will require access to a graphical tool such as
|
||||
[pgAdmin](https://www.pgadmin.org/download/) (highly recommended) or a PostgreSQL terminal (`psql`) for advanced users.
|
||||
The Windows PostgreSQL installation will come with a version of pgAdmin.
|
||||
|
||||
To use pgAdmin, run the appropriate binary to start the pgAdmin server. Depending on the version, a tab in your web
|
||||
browser will open, or maybe a dedicated application window will open. Either way, create necessary passwords during
|
||||
the first login, then enter the connection details that were used during the PostgreSQL installation. When connected,
|
||||
expand the tree and right click on "Databases", menu -> Create... -> Database. Enter name as "psforever", then Save.
|
||||
Right click on the psforever database, menu -> Query Tool... Copy and paste the commands below, then hit the
|
||||
"Play/Run" button. The user should be created and made owner of the database. (Prior to that, it should be "postgresql".)
|
||||
(Check menu -> Properties to confirm. May need to refresh first to see these changes.)
|
||||
```sql
|
||||
CREATE USER psforever;
|
||||
ALTER USER psforever WITH PASSWORD 'psforever';
|
||||
ALTER DATABASE psforever OWNER TO psforever;
|
||||
```
|
||||
**NOTE:** applying default privileges _after_ importing the schema will not apply them to existing objects. To fix this,
|
||||
*you must drop all objects and try again or apply permissions manually using the Query Tool / `psql`.
|
||||
**IMPORTANT NOTE**: applying privileges _after_ importing the schema will not apply them to existing objects.
|
||||
If this happens, drop all objects and try again or apply permissions to everything manually using the Query Tool / `psql`.
|
||||
|
||||
The server will automatically apply the latest schema. Migrations can also be applied manually using the [Flyway
|
||||
CLI](https://flywaydb.org/documentation/commandline/). Existing databases before the introduction of migrations must be
|
||||
baselined using the `flyway baseline` command.
|
||||
### Using an IDE
|
||||
Scala code can be fairly complex, and a good IDE helps you understand the code and what methods are available for certain
|
||||
types, especially as you are learning the language. IntelliJ IDEA has some of the most mature support for Scala of any
|
||||
IDE today. It has advanced type introspection (examine the properties of an object at runtime) and excellent code
|
||||
completion (examine the code as you are writing it).
|
||||
Download the [community edition of IDEA](https://www.jetbrains.com/idea/download/) directly from IntelliJ's website
|
||||
then get the [required Scala plugin for IDEA](https://www.jetbrains.com/help/idea/managing-plugins.html).
|
||||
|
||||
### Becoming a GM
|
||||
You will need to import the project into the IDE. Older versions of IDEA (2016.3.4, etc.) have an
|
||||
[import procedure](https://www.lagomframework.com/documentation/1.6.x/scala/IntellijSbt.html)
|
||||
where it is necessary to instruct the IDE what kind of project is being imported. Modern IDEA (2022.1.3) still
|
||||
utilizes this procedure but can also open the repo as a project and contextually determine what
|
||||
is being expressed by the code (much better than older versions can, anyway). Certain aspects will need to be
|
||||
clarified manually if this method is utilized, e.g., the JDK and JRE, since those choices were skipped. When the
|
||||
project is fully imported, create a new run configuration using the dropdown near the top of the interface.
|
||||
Create an sbt task configuration with the specific task instructions `server/run`. Confirm. Press the green arrow
|
||||
"Run") to launch the server.
|
||||
|
||||
By default users are not granted GM access. To grant a created user GM access execute the following query:
|
||||
|
||||
```sql
|
||||
UPDATE accounts SET gm=true WHERE id=your_id;
|
||||
```
|
||||
|
||||
You can find your account id by viewing the accounts table.
|
||||
### Using a Text Editor
|
||||
If you are not a fan of big clunky IDEs, and IDEA is definitely one of them, you can opt to use your favorite text
|
||||
editor - VSCode, Sublime, ViM, Notepad++, Atom, etc - and use sbt to build the project. The only dependencies
|
||||
necessary are sbt and access to the JDK. Everything else should be deployed from working with those. Run
|
||||
commands in a command line tool with appropriate dependency visibility to start the server.
|
||||
|
||||
## Running the Server
|
||||
The initial compile may take some time. Sbt is powerful but slow to wake up.
|
||||
|
||||
### Startup
|
||||
To run a headless, non-interactive server, run
|
||||
|
||||
```
|
||||
sbt server/run
|
||||
```
|
||||
|
||||
PlanetSide can now connect to your server.
|
||||
|
||||
To run your custom server with an interactive `scala>` REPL, run
|
||||
|
||||
```
|
||||
sbt server/console
|
||||
```
|
||||
|
||||
|
||||
|
||||
To start the server and begin listening for connections, enter the following expression into the REPL:
|
||||
|
||||
```
|
||||
Server.run
|
||||
```
|
||||
|
||||
|
||||
|
||||
This process is identical to running the headless, non-interactive server: PlanetSide clients can connect, logging
|
||||
output will be printed to the screen, etc. The advantage is that you now have an interactive REPL that will evaluate any
|
||||
Scala expression you type into it.
|
||||
|
||||
|
||||
|
||||
The REPL supports various useful commands. For example, to see the type of an arbitrary expression `foo`, run `:type
|
||||
foo`. To print all members of a type, run `:javap -p some-type`. You can run `:help` to see a full list of commands.
|
||||
|
||||
|
||||
|
||||
## Creating a Release
|
||||
The game server will automatically apply the latest schema to the database, updating sequential entries found in
|
||||
`resources/db/migrations`. Migrations can also be applied manually using the
|
||||
[Flyway CLI](https://flywaydb.org/documentation/commandline/).
|
||||
Existing databases before the introduction of migrations must be baselined using the `flyway baseline` command.
|
||||
|
||||
### Tests
|
||||
Tests that are packaged with the server project code can also be run using the command `sbt test`. The anticipated
|
||||
`/test/` directory should be reachable under the `/src/` directory. IntelliJ IDEA allows hinting of the directory from
|
||||
the context menu of the Project tab: `menu -> Mark Directory as -> Test Sources Root` or `Test Resources Root`.
|
||||
|
||||
### GM
|
||||
By default users are not granted game moderator privileges, colloquially referred to as a customer service representative (CSR).
|
||||
To grant a created user GM, access execute the following query:
|
||||
```sql
|
||||
UPDATE account SET gm=true WHERE id=[your_id];
|
||||
```
|
||||
You can find your account id by viewing the accounts table.
|
||||
```sql
|
||||
SELECT id FROM account WHERE username=[your_username];
|
||||
```
|
||||
|
||||
### Creating a Release
|
||||
If you want to test the project without an IDE or deploy it to a server for run, you can use sbt-pack to create a
|
||||
release (included with the repository). First make sure you have the [sbt tool](http://www.scala-sbt.org/download.html)
|
||||
on your command line (or create a new task in IntelliJ IDEA). Then get a copy of the source directory (either in ZIP or
|
||||
cloned form). Then do the below
|
||||
|
||||
```
|
||||
cd PSF-LoginServer
|
||||
sbt packArchiveZip # creates a single zip with resources
|
||||
```
|
||||
|
||||
This will use the sbt-pack plugin to create a JAR file and some helper scripts to run the server. The output for this
|
||||
will be in the `PSF-LoginServer/target` directory. Now you can copy the ZIP file to a server you want to run it on. You
|
||||
will need the Java 8 runtime (JRE only) on the target to run this. In the ZIP file, there is a `bin/` directory with
|
||||
some helper scripts. Run the correct file for your platform (.BAT for Windows and shell script for Unix).
|
||||
|
||||
### Generating Documentation
|
||||
|
||||
Using sbt, you can generate documentation all projects using `sbt docs/unidoc`.
|
||||
|
||||
Current documentation is available at [https://psforever.github.io/PSF-LoginServer/net/psforever/index.html](https://psforever.github.io/PSF-LoginServer/net/psforever/index.html)
|
||||
## Troubleshooting
|
||||
1. If dependency resolution results in certificate issues or generates a `/null/` directory into which some library
|
||||
files are placed, the Java versioning is incorrectly applied. Your system's Java, via `JAVA_HOME` environment variable,
|
||||
must be advanced enough to operate the toolset and only the project itself requires JDK 8. Check that project settings
|
||||
import and utilize Java 1.8_251. Perform normal generated file cleanup, e.g., sbt's `clean`.
|
||||
Any extraneous folders may also be deleted without issue.
|
||||
2. If the server repeatedly complains that "authentication method 10 not supported" during startup, your PostgreSQL
|
||||
database does not support [scram-sha-256](https://www.postgresql.org/docs/current/auth-password.html) authentication.
|
||||
Check in your database configuration file `postgresql.conf` that `password_encryption` is set correctly; or, upgrade
|
||||
your PostgreSQL version to one that supports scram-sha-256. Whenever changing password encryption methods, all
|
||||
existing passwords FOR THE USERS AND ROLES should be rehashed for the new encryption.
|
||||
|
||||
## Tools
|
||||
|
||||
### decodePackets
|
||||
|
||||
The decodePackets program can be used to decode GameLogger `.gcap` packet captures. Requires
|
||||
[gcapy](https://github.com/psforever/gcapy) to run, unless the `-p` flag is used.
|
||||
|
||||
To build, run:
|
||||
|
||||
```
|
||||
sbt decodePackets/pack
|
||||
```
|
||||
|
||||
The output will be in `tools/decode-packets/target/pack`. The `bin` folder contains scripts to
|
||||
launch the program. On Linux, you can use the Makefile to install the files to any path:
|
||||
|
||||
```
|
||||
make install PREFIX=$HOME/.local
|
||||
```
|
||||
|
||||
Now you can run the program like that:
|
||||
|
||||
```
|
||||
psf-decode-packets -o ./output-directory foo.gcap bar.gcap
|
||||
```
|
||||
|
||||
By default, decodePackets takes in `.gcap` files, but it can also take gcapy ascii files with the
|
||||
`-p` option. Run `psf-decode-packets --help` to get usage info.
|
||||
|
||||
## Contributing
|
||||
### Generating Documentation
|
||||
Using sbt, you can generate documentation all projects using `sbt docs/unidoc`.
|
||||
Current documentation is available at [https://psforever.github.io/PSF-LoginServer/net/psforever/index.html](https://psforever.github.io/PSF-LoginServer/net/psforever/index.html)
|
||||
|
||||
Please fork the project and provide a pull request to contribute code. Coding guidelines and contribution checklists
|
||||
coming soon.
|
||||
## Contributing
|
||||
Please fork the project and provide a pull request to contribute code. ~~Coding guidelines and contribution checklists
|
||||
coming soon.~~
|
||||
|
||||
## Get in touch
|
||||
|
||||
- Website: http://psforever.net
|
||||
- Discord (chat with us): https://discord.gg/0nRe5TNbTYoUruA4
|
||||
- Join the #code channel and ask any questions you have there
|
||||
|
||||
## License
|
||||
|
||||
GNU GPLv3. See LICENSE.md for the full copy.
|
||||
|
|
|
|||
|
|
@ -81,6 +81,9 @@ lazy val psforeverSettings = Seq(
|
|||
"org.scala-lang.modules" %% "scala-parallel-collections" % "1.0.4",
|
||||
"org.bouncycastle" % "bcprov-jdk15on" % "1.69"
|
||||
),
|
||||
dependencyOverrides ++= Seq(
|
||||
"com.github.jasync-sql" % "jasync-postgresql" % "1.1.7"
|
||||
),
|
||||
// TODO(chord): remove exclusion when SessionActor is refactored: https://github.com/psforever/PSF-LoginServer/issues/279
|
||||
coverageExcludedPackages := "net\\.psforever\\.actors\\.session\\.SessionActor.*"
|
||||
)
|
||||
|
|
|
|||
Loading…
Reference in a new issue